Re: [boost] Improving Documentation

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.

If I was given unlimited time, a text editor and asked to handcraft HTML pages with ideal documentation for a library, I would have trouble to imagine a complete picture of it.

Ahhh - don't use your imagination!!! Look at the docs for our various libraries. These cover a wide span in library type and functionality, scale, toolset used. Ask yourself which of the libraries did you find the easiest to use? Which made you want to tear your hair out. I've mentioned some models - patterns and anti-patterns.

I may know my library well, but it does not mean I know how to describe it well. (I may be a capable mathematician, but a rubbish teacher :))

I totally get this. I made the serialization library and no one knew (or knows) it as well as I do. I wrote the first cut documentation and thought it was good. I caught hell for this. (I still say it wasn't THAT bad) but given the advice of a lot of really bad explainers here, and constant tweaks in response to users who complain about stuff, it's gotten to the point to where I don't get too many complaints.

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. I've also tried to make a sort of "form filling" approach to documentation of at least reference part of the documentation.

I know it may sound like delegating a work,

lol - well, that's what libraries are!

but I personally seek for mentoring here.

I think the fact that you're following this discussion - apparently others are as well - is a good start. Robert Ramey