Joaquín Mª López Muñoz <joaquin@tid.es> writes:
David Abrahams ha escrito:
David Greene <greened@obbligato.org> writes:
E. Is the documentation good enough for a boost library?
This has been made very clear and Andy has graciously accepted
the suggested documentation changes.
Andy has indeed graciously accepted criticism of the documentation,
for which I commend him.
What's missing for me is a clear intention to actively pursue better
docs himself, as opposed to being willing to accept specific edits
that other people happen to suggest. If we leave the quality of our
documentation (or code, for that matter) up to people who rewrite it
for us, we won't have much quality at all. IMO the library author
has to be willing to take responsibility for making the docs work; any
help from the outside is a bonus.
There's an alternative: convincing someone else other than the
programmer to become the long-term documenter of the lib.
Sure, that's fine, if the person presenting the library as a Boost submission does it, and before the review. But then, if that's handled, the docs will probably have been cleaned up well before the review starts.
Producing quality documentation for a library is a challenging and
rewarding task and distributing responsibilities among several
people might work better than expecting authors to excel at coding
as well as documenting. Now, not that we have a pool of aspiring
documenters, but it we publicized the position a little some
volunteers might appear, for specific libs at least.
Tried that already; we need someone to take a leadership position in documentation. There was a guy we appointed to be the "documentation wizard" last year but he disappeared. -- Dave Abrahams Boost Consulting www.boost-consulting.com