Re: [boost] [IBD] Request for Comment, Objectives

From: Matias Capeletto (matias.capeletto_at_[hidden])
Date: 2007-07-08 19:45:49

On 7/8/07, David Abrahams <dave_at_[hidden]> wrote:
>
> 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
> > release.
>
> 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

Ok.

>  * learning to think about your code as though you don't already
>    understand it

Very difficult one for the author, at least it was in my case.
We can help authors because we it is not our code.

>  * learning to omit needless words

Important one. In my case, I have asked help to others to reread my
docs and they have delete a lot of unnecessary words leaving the text
more clear and to the point.

>  * learning to set expectations appropriately.  Producing quality
>    documetation typically takes as much -- or more -- time than
>    writing the code that is documented.

Totally agree.

> etc...
>
> I don't know who is watching out for these things, but IMO they are
> essential elements of any effective IBD campaign.

I will add this points to the objectives of IBD under quality
documentation, and mention that we will help authors to improve their
docs content.

Thanks for spotting a clear miss from the objectives.

King regards
Matias