Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2013-10-11 13:19:29

On 11 Oct 2013 at 14:46, Mathias Gaunard wrote:

> > I completely agree that boost docs should generally be a "how to use"
> > guide. The additional steps I also think would be reasonable are for the
> > "how to use" detail to be easier to browse around and links to all the
> > existing examples and tests.
> 
> There are two parts to a documentation:
>   - a reference documentation, which says non-ambiguously what a 
> function does, what its preconditions are, which file it is in, etc.
> It is easy to agree upon the fact that this documentation should be 
> written with Doxygen to ensure that it's always in sync with real code.
>   - a tutorial, that explains the domain and how to approach using the 
> library to solve some problems. This is better written separate from the 
> library using Quickbook (or ReST or any other similar language).
> 
> Standardizing all Boost documentation for the reference part would be 
> great IMHO.
> Each library seems to do its own thing for this, with varying levels of 
> quality.

I really think the Design Rationale, which is recommended by the 
Boost wiki, is absolutely vital and often the most important part of 
a Boost library's documentation. AFIO's design rationale is huge, 
because I recognised most will disagree with its design and/or not 
get the point of the library :)

Boost libraries often make unusual design choices compared to say a 
Python or C# or especially Java equivalent. These choices are usually 
due to (a) C++ convention (b) the fact we can metaprogram the 
compiler (c) the unique algorithmic complexity guarantees C++ can 
make, which sometimes require inconvenience on the part of the 
programmer.

A good design rationale tells you where the library author(s) was 
coming from, why they made the tradeoffs they did, and why some 
aspect of the library appears really stupid on the surface but in 
fact is a least worst choice given the alternatives. It's a bit 
philosophical sure, but it helps to save having to attend C++ Now 
presentations before you can even try to wrap your head around a 
library. It's also material that no tutorial nor reference 
documentation can convey.

Niall

-- 
Currently unemployed and looking for work.
Work Portfolio: http://careers.stackoverflow.com/nialldouglas/