Re: Recommendations for documentation authors

From: Robert Ramey (ramey_at_[hidden])
Date: 2024-01-02 20:16:28

> 
> So, when you are recommending QuickBook, does this also imply
> BoostBook/DocBook, or are you treating them as separate tools?
> 
> Regards,
> &rzej;
> 

I here's my story with boost documentation tools.  I've described my 
views on documentation content elsewhere:

https://www.youtube.com/watch?v=YxmdCxX9dMk

I always liked the xml approach of separating document content from 
document rendering.  This permits one to create the content one time and 
render it according to one's desire at the time.  Thus one can produce 
HTML, PDF, (probably AsciiDoc) and who knows what else.  One could also 
create an xmlsltproc file which would automatically generate a global 
table of contents for one or all boost libraries - though this has never 
been done.  It also permitted the creating of custom "vocabularies" 
which would specify more meta data about the content.  Doug Gregor 
created all this in BoostBook but it hasn't been exploited much if any.

There remained a few problems though.

Editing XML is/was not a user friendly operation.  Eric Niebler 
addressed this by writing QuickBook which produced XML from a simpler 
text format. This was well received by Boost developers and likely saved 
XML from failure.

I didn't like:

The tool chain used B2 to transform the XML into html by invoking 
xsltproc.  I found this to be akin to training an ant to train a flea 
and too hard for me to do and to keep up with.  To this day I have 
difficulties with B2.

I addressed this by editing the raw BoostBook with an XML editor: 
XMLMind.  This is a gui editor which I fund easy to use and lets me 
visualize the final documentation product as I type.  It's also friendly 
about using "templates" for things like template, class, and function 
reference documentation. I use a simple shell script to invoke xsltproc 
to generate html and pdf versions of my docs.

I didn't like the usage of DOxygen.  I've found this tool to be unsuited 
to writing documentation of code based on requirements (C++ templates) 
as opposed to code based on classes.  My XML editor easily let me use 
"templates" for the things I need so no need to try to get DOxygen to do 
what I needed to do or tweak my C++ comments to make DOxgen do what I 
wanted.

Finally, I ship pre-built documents with my libraries.  So anyone who 
can look up any part of the documentation without having to go on line 
to do so or with having to build (via B2) A local copy.  OK it takes a 
little extra space. But it's worth it so that users can get immediate 
answers to their question.  It's also easy for them to send a steady 
stream of typos that I continually correct.

Robert Ramey