Re: [boost] Improving Documentation

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
mentoring here.

Best regards,
-- 
Mateusz  Loskot, http://mateusz.loskot.net