Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2011-10-06 23:24:52

On 05/10/11 11:55, Paul A. Bristow wrote:
> Dave Abrahams wrote: 

> 2  The results of Pierre Talbot, the GSoC student that I mentored
> this summer (and put the hard word on him to write the docs using
> these tools - including switching on a Doxygen switch that nags you 
> if you fail to document every class, function etc).
> 
> For his Quickbook toolchain generated docs see
> 
> https://svn.boost.org/svn/boost/sandbox/SOC/2011/checks/libs/checks/doc/html/index.html
>
> [...]
> You can compare what you get by looking at the 'Checks Reference
> section' and the 'Class list' and choosing a class to find what they
> might do for you.

In my opinion, docs formatted/presented like this

https://svn.boost.org/svn/boost/sandbox/SOC/2011/checks/libs/checks/doc/html/boost/checks/luhn_algorithm.html

will put most readers off. Looks terrible, if I may express my opinion.

Format and layout of class documentation in the standalone version
is way better.

I still vote for Boost.Asio docs as an examplar.

First page displays clearly indicates what user can expect form the
documentation:

http://www.boost.org/doc/libs/1_47_0/doc/html/boost_asio.html

Reference displays all elements according to physical and logical
structure of the software components:

http://www.boost.org/doc/libs/1_47_0/doc/html/boost_asio/reference.html

A single class page gives overview description, members summary
and usage example - no more-and-too-detailed information presented:

http://www.boost.org/doc/libs/1_47_0/doc/html/boost_asio/reference/streambuf.html

A class member page follows exactly the same convention as above:

http://www.boost.org/doc/libs/1_47_0/doc/html/boost_asio/reference/basic_streambuf/size.html

If it is a template, then corresponding type requirements are linked.

Every page of a reference is structured and formatted according to the
same rules. This makes it extremely easy to get familiar with
documentation. User needs to visit two pages at most to learn how to
read the documentation.

IMO, it would be beneficial if every library in Boost follows consistent
convention, so switching from library X to Y does not
change the way user navigates and reads the documentation
Think of MSDN for Boost.

The quality of discoverability does not only applies to API of software
but also to technical documentation, IMO.

> Other 'concepts' like Concepts that are not part of the C++ language
> could be accommodated by convention using the \note or \remark
> comments?

IMO, it's not enough.

> Finally do not forget that you can get an *index* of all this, for
> zero or modest effort. How many times have I forgotten what a Boost
> function or macro is called or does?  An index would have saved so
> much Googling (and bad language and blood pressure elevation!)

It is a nice feature, but IMO it is rated not higher than 5-6
in from 1 to 10. Reading documentation is tangent and parallel to
learning about a library. I start using index once I passed
beginner (and even intermediate) level of documentation reading.

> Now I'm not pretending that all this comes for free - it does mean a
> lot more work for the author (and it clutters the source code),

The code clutter is pointed as major drawback of Doxygen use.

> but IMO the results are vastly more useful to the *user* and well worth
> the effort.

My own manifest is:
- Standalone native Doxygen doc is useful as API reference.
- Standalone native Doxygen doc is not useful as a handbook-like
documentation.
- Boost documentation is not only API reference, but a handbook.

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org
Member of ACCU, http://accu.org