From: David Abrahams (dave_at_[hidden])
Date: 2007-07-08 19:09:16
on Sun Jul 08 2007, "Matias Capeletto" <matias.capeletto-AT-gmail.com> wrote:
> Although Boost has one of the greatest documentation available in Open
> Source projects, we think that it can be improved. For example, a
> consistent look and feel through Boost libraries will help users to
> understand that Boost is not simple a collection of quality pieces,
> but an amazing always evolving maze that must be seen as whole.
> IBD main purpose is to be another quality reassurance mechanism,
> trying that Boost Docs be in the better shape possible for each
I agree that developing a consistent and improved look & feel is
important. However it is at _least_ as important to develop skills
and best practices that produce good documentation content. That
means, among other things:
* learning to write precisely, without ambiguity
* learning to think about your code as though you don't already
* learning to omit needless words
* learning to set expectations appropriately. Producing quality
documetation typically takes as much -- or more -- time than
writing the code that is documented.
I don't know who is watching out for these things, but IMO they are
essential elements of any effective IBD campaign.
-- Dave Abrahams Boost Consulting http://www.boost-consulting.com The Astoria Seminar ==> http://www.astoriaseminar.com
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk