Re: [boost] Improving Documentation

On 12 October 2013 22:29, Robert Ramey wrote:

Mateusz Loskot wrote:

...

On 12 October 2013 18:59, Eric Niebler 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