Re: [boost] Improving Documentation

On 10 October 2013 23:47, Andrew Hundt wrote:

On Thu, Oct 10, 2013 at 6:01 PM, Niall Douglas wrote:

...

On 10 Oct 2013 at 15:00, Andrew Hundt wrote:

...

So, is there anything we can do about it?

I remember a couple of years ago Boost had a "Bug Sprint" with the goal of closing lots of open tickets. Perhaps we should do a "documentation sprint"?

Historically Boost's libraries were sorta seen as proto-standard libraries, so their documentation was written in the style of the ISO C++ standard i.e. it assumes you already understand the patterns used in the library, and all you need is the "how to use" detail.

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.

Something that would truly be great would be for each function to be called in some example.

That's what we aim in the API reference of Boost.Geometry - a reasonable self-contained example at the bottom of each page. For example http://www.boost.org/doc/libs/1_54_0/libs/geometry/doc/html/geometry/referen... AFAIR, we've got this idea from Boost.Spirit/ Best regards, -- Mateusz Loskot, http://mateusz.loskot.net