OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

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



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?




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...


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]