Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2013-10-12 17:29:14

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.

> 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