Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2013-10-10 19:03:31

On 10 October 2013 23:47, Andrew Hundt <athundt_at_[hidden]> wrote:
> On Thu, Oct 10, 2013 at 6:01 PM, Niall Douglas <s_sourceforge_at_[hidden]>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/reference/algorithms/area/area_1.html

AFAIR, we've got this idea from Boost.Spirit/

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