Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2013-10-11 12:51:01

"Edward Diener" <eldiener_at_[hidden]> wrote in message 
news:l38fk4$p76$1_at_ger.gmane.org...
> 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.
>
>
>
>
> _______________________________________________
> Unsubscribe & other changes: 
> http://lists.boost.org/mailman/listinfo.cgi/boost
>