Katie,
I started my IT career working with IBM mainframes. Mainframers live in a parallel upside down universe where simplicity is complexity and the more you need to know about something the more worthy it is of your admiration. When I first started selling software I learned the hard way that most people “IT professionals” don’t know how to open a command prompt. So if it isn’t as easy as their iPhone to use you don’t make a sale. To make matters worse, most people are incapable of understanding a manual, even if you have one and it is well written. So in the end, as a software vendor you need to have: 1. Support people to do the work for the 70% of people who can’t do it for themselves even with a manual. 2. YouTube videos for the 15% of people who would rather watch a How-To video than read a manual. 3. A manual in web, PDF and hardcopy for those who insist on having a manual (who are the other 15% + some of the people above). Other people might be seeing different things, but this is my experience. The end result is that written manuals are only there for about 1 in 7 of my customers, and completely irrelevent to the others. Do they teach people doing IT/Technology at University how to write documentation (or did they ever)? If they do teach them, what platforms are they taught about? Gerard From: Katie Welles [mailto:[email protected]] Sent: Sunday, September 13, 2015 10:12 AM To: [email protected] Subject: Re: [docbook-apps] Show off what you've done with Docbook Gerard's points 1 and 2 are quite valid. Setting up my DocBook toolchain was quite the graduate course in frustration. I wrote up notes about how I set it up here: http://www.millermattson.com/blog/docbook-toolchain/, mostly so I could do it again years later after forgetting! And my client wanted quite a few customizations, so I had to delve very deeply into the XSLT which is an intricate tapestry of spaghetti. I ended up with a pretty intense customization chain, but even then, there were some nits I was never quite able to figure out. If I can find those notes I’ll post those on my blog, too. I still say that the power of DocBook is not in its ability to create documents, but in its ability to output a document **and** HTML from the same source. But when i worked with it, we only generated HTML. And for all the monumental hassle of dealing with the toolchain + tortuously laboring in the XSLT, to just get a simple HTML site at the end was sad: I could have created something so much nicer in just straight HTML +CSS! I've seen some pretty nice documents in this thread, but not so many HTML-plus-PDF pairs of documents (although I have yet to sit down and look at all the responses to this thread yet). I think a nice looking document is fine — but it is a nice-looking document **paired with** navigable HTML is the real win. The HSA Foundation specs, PDF and HTML, were output from a single data source. http://www.hsafoundation.com/html/HSA_Library.htm We used Madcap Flare for this project, which is a fantastic tool with a price tag and learning curve which IMHO removes it from consideration outside of the corporate setting. So I’m still looking… and I’m not sure DocBook will cure this ill... K.
