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
> 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.
> 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.
-- Mateusz Loskot, http://mateusz.loskot.net
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk