Re: [boost] Improving Documentation

On 13 October 2013 22:57, Robert Ramey wrote:

Mateusz Loskot wrote:

...

On 12 October 2013 22:29, Robert Ramey 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