Re: [boost] Writing documentation

Subject: Re: [boost] Writing documentation
From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2013-02-02 05:00:34

On Saturday 02 February 2013 11:46:19 Borislav Stanimirov wrote:
> Hello,
> 
> I'm developing a project for boost (discussion can be found here:
> http://lists.boost.org/Archives/boost/2013/01/200598.php)
> 
> I was wondering how one writes documentation. I did find some templates
> here, but they seem outdated (ot at least different), compared to the
> documentation files that already exist for the libraries.
> 
> So, are there any new templates? Is there a html generation tool I
> should use?

I found QuickBook to be the easiest tool for documenting Boost libraries. You 
can find its docs on the site:

http://www.boost.org/doc/libs/release/doc/html/quickbook.html

The docs are written in QuickBook themselves so that's what your docs will 
look like in the end. On the front page you will find a link to quickbook.qbk 
which you can use as a starting point.

There are no requirements on the documentation structure, AFAIK. But generally 
it is a good idea to provide a tutorial, some expanded description and formal 
reference sections. Of course, it all depends on how large and complex the 
library is; sometimes it is enough to just have a tutorial if the library is 
small.