Subject: Re: [boost] Improving Documentation
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2013-10-12 14:25:03
On 12 October 2013 18:59, Eric Niebler <eniebler_at_[hidden]> wrote:
> I'll add my voice to those who find the header-first reference layout
> less than ideal, although I say that without a concrete suggestion for
> improving it.
My own impression, after numerous docs discussions, is that we've been
exchanging random bullets of pros and cons, advantages
and disadvantages, tool A vs tool B, example X vs example Y,
but still, we haven't near to the point of a compromise on
an ideal (or optimal) Boost documentation for a library.
If I was given unlimited time, a text editor and asked to
handcraft HTML pages with ideal documentation for a library,
I would have trouble to imagine a complete picture of it.
I may know my library well, but it does not mean I know how to describe it well.
(I may be a capable mathematician, but a rubbish teacher :))
I've been hoping the Boost community can take smallest Boost library which
contains most of C++ elements and make its docs an example of
systematic approach (a flowchart) on writing documentation for a Boost library.
I know it may sound like delegating a work, but I personally seek for
-- Mateusz Loskot, http://mateusz.loskot.net
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk