Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2013-10-13 20:56:35

On 13 October 2013 22:57, Robert Ramey <ramey_at_[hidden]> wrote:
> Mateusz Loskot wrote:
>> On 12 October 2013 22:29, Robert Ramey <ramey_at_[hidden]> wrote:
>>> I've also tried to make a sort of "form filling"
>>> approach to documentation of at least reference part  of the
>>> documentation.
>>
>> I think a kind of a flowchart approach would be helpful:
>
> <snip>
>
>> IOW, a systematic top-bottom approach to documenting.
>
> a little to detailed for my taste.  I prefer to focus slightly differently:
> Try to agree on what boost accept should contain, and leave the
> exact procedure and tools to be used to each author.

Yes, I was trying to make it clear tools are not the important part
of guidelines. A procedure is important and I don't mean
number/order of steps, those make rough illustration.
I mean guidelines on what needs to be documented and how, precisely.
If you have concepts, document it this way...etc.

Authors may use their own tools, procedures, but the output should
be consistent in terms of list of mandatory elements, form and format
across all Boost libraries. IMHO, no room for compromise here.

Every book published by O'Rreilly, looks, feels and navigates the same.

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