RE: [docbook-apps] Show off what you've done with Docbook

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:katie@inkwelle.com]
Sent: Sunday, September 13, 2015 10:12 AM
To: docbook-apps@lists.oasis-open.org
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...

docbook-apps message