Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2013-10-15 12:41:56

Mateusz Loskot wrote:
> Tools are crucial, but we haven't decided *what* those tools are
> supposed to do (extracting and hyperlinking bits of comments is not
> enough).

> Let's *forget* about the tools and focus on creating the "form
> filling" framework,
> creating the Boost documentation structure with gaps to be filled
> with content. From the docs quality perspective, it does not really
> matter how we
> fill those gaps,
> manually or with the tools.
> Certainly, from productivity and such perspective, tools are crucial,
> but we still
> haven't decided what those tools would do :)
>
> IMHO, we try to solve micro-problems of markup and tools too early,
> whereas we should
> rather stick to top-bottom approach.

+1

Here's the link to my own proposal for a "form filling" approach:
http://rrsd.com/blincubator.com/requirements_documentation/

>> As an test example, it's also a bit of a googly because Fusion a bit
>> of a weird and wonderful meta-language-ish beast.
>>
>> Another test-case example?

Here's my test case example:

http://htmlpreview.github.io/?https://raw.github.com/robertramey/safe_numerics/master/safe_numerics/doc/html/index.html

> I'll follow Robert's suggestion: enable_if, Fusion, Iostreams, MPL,
> Spirit.

I'm sure there are others - I haven't studied all of boost in detail.

> Why? The meta aspect of a library bumps the complexity of documenting it,
> so it's good to tackle meta-language-ish beasts first.

+1  - first decide what - then decide how - or better yet - let the person
who does decide how.

> To summary, let me repeat what is *my* problem with documenting Boost,
> what I have been grinding in this thread in almost every post:
>
> 1. I have created my first library Boost.XYZ.
> 2. I haven't put a single line of C++ comment in Boost.XYZ sources.
> 3. I have collected all the tiniest details about every template,
> class, function, concept, pre-/post-condition, ... in my head.
> 4. I need forms or templates that I can fill with *all* those details
> I have collected about Boost.XYZ?
> 5. I will be filling those forms manually, in my favourite text
>    editor. NOTE: I don't want to learn new language (yet [1]) to
> document my
> library, it must be no-brainer boring form filling [2]
> 6 .I will pass the filled forms  (doc source files) to the Boost
> Documentation repo to generate HTML pages at
> http://www.boost.org/libs/xyz/
>    where *all* those details will be presented in canonical way (SGI
> STL, Robert's examples), using consistent formatting and typography,
>    properly interlinked (concepts, refinements, models,...), <all the
> fancy output features here>
> 7. Where can I find the forms?

http://rrsd.com/blincubator.com/tools_documentation/

describes what has worked for me.

> [1] Learning new language or tool shall be necessary *only* if I want
> to use it, but may like manual labor of writing from top of my head
> [2] Implies easy automation with tools
>
> Are the expectations outlined above invalid and I'm misunderstanding
> the whole problem?
> If yes, then I'll rewind, go back and seek to learn the right way.

The whole thrust of your email resonates with my feelings about the
subject.

Robert Ramey