On 12 October 2013 18:59, Eric Niebler
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