Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2013-10-13 16:12:28

On 12 October 2013 22:29, Robert Ramey <ramey_at_[hidden]> wrote:
> Mateusz Loskot wrote:
>> On 12 October 2013 18:59, Eric Niebler <eniebler_at_[hidden]> wrote:
>>>
>>> I'll add my voice to those who find the header-first reference layout
>>> less than ideal, although I say that without a concrete suggestion
>>> for improving it.
>>
>> My own impression, after numerous docs discussions, is that we've been
>> exchanging random bullets of pros and cons, advantages
>> and disadvantages, tool A vs tool B, example X vs example Y,
>> but still, we haven't near to the point of a compromise on
>> an ideal (or optimal) Boost documentation for a library.
>
> I don't think the discussion is all THAT random.  I've more or less
> expressed a desire for more formal, regular SGI like documentation
> and I don't think anyone has said that's not an unworthy goal.
>
> The fact that we don't have ideal tools makes it harder to atain this
> though.
>
> I don't feel we all have to agree.

I agree. I just said, it's an impression.

>> I've been hoping the Boost community can take smallest Boost library
>> which contains most of C++ elements and make its docs an example of
>> systematic approach (a flowchart) on writing documentation for a
>> Boost library.
>
> We're on the same page here.

Good.

> I've mentioned a few libraries which I think should be used as models.

Your summary is very helpful. I'll keep looking at the examples you've
given (enable_if, Fusion, Iostreams, MPL, Spirit).

> 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:

Step 1: Public namespace(s)? -> Create .qbk/.xml file per namespace,
write/format/arrange paragraphs, ...

Step 2: Concepts? -> Create file per concept, create table with this header,
these # of columns, use this formatting to indicate  link to header(s)
like this, ...

Step 3: Refinements?  Create file..., make table.., link to base
concept this way

Step 4: Models? -> Do ...
Step 5: Macros? -> Do ...
Step 6: Building and installation? -> Do ...
...
Step #: Generate HTML output

IOW, a systematic top-bottom approach to documenting.

Each of those steps, apart form the last one, do not need to even
mention any of Quickbook/Boostbook tools in details, but just minimum
guidelines related to format of choice:
if you write Quickbook, refer to these
guidelines for concepts and refinements formatting;
if you write Boostbook, ...

All the technical choices in each of those steps are "form filling" no-brainers.

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