Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Edward Diener (eldiener_at_[hidden])
Date: 2013-10-11 05:15:30

On 10/11/2013 4:52 AM, Paul A. Bristow wrote:
>> -----Original Message-----
>> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Robert Ramey
>> Sent: Friday, October 11, 2013 3:11 AM
>> To: boost_at_[hidden]
>> Subject: Re: [boost] Improving Documentation
>>
>> Andrew Hundt wrote:
>>> I have to say Boost's documentation is generally excellent.
>>
>> Thanks for indulging me - I trying hard not to rant.
>
> I'll try hard too ;-)
>
> We *still* don't have a single example of using *ALL* the tools we already have to prepare
> documentation.  All the examples of deficiencies you note *can* be met - except the docs being small
> files and quick to build (but size doesn't matter provided one can navigate around well).
>
> Quickbook provides a nice markup system for plain text - and it provides the hooks and eyes to get
> to code snippets and Doxygen comments.
>
> Doxygen (as used in this toolset) provides a way to add code comments to all the code elements -
> functions, data, macros etc.  Using it with Quickbook is only a way to link these comments to the
> C++ reference section so that you can click on any function name and find its description,
> preconditions, post conditions, parameter and template parameters descriptions.
>
> *These descriptions are the key things that are missing for most Boost documentation*.
>
> The usefulness of the docs is mainly determined by the work that goes into these descriptions.
>
> Autoindex provides an index - automatically for all the above C++ elements, and manually given some
> work.  All the index items are hyperlinks.  Boost.Math shows this in action - though it needs more
> manually added index terms - more work!
>
> PDF single file that can be printed like a book (as well as HTML).
>
> Many libraries use some tools, but none use *ALL* of them.
>
> I've recently re-factored the circular_buffer library using all these tools.
>
> (But I'm not the author so I can't claim to make as good a job as someone who really understands the
> code could do - it's only a refactoring).
>
> Maybe you'd comment again when you've seen this example.

As you say the tools are there. But I do not think the difficulty of 
some of the docs are a matter of tools. I believe it is a matter of the 
structure of the documentation for some of the libraries and also that 
programmers typically are much more focused on correct code than they 
are on really good documentation. Some Boost documentation is really 
excellent while some other Boost documentation assumes a great deal on 
the part of the programmer using the library and explains much less of 
the general concepts of the libary than it could. I am one of those who 
believe that a thorough overview of a library is very important, even 
more important than examples, but then I am probably deficient myself in 
providing examples for libraries I write.