On 7/8/07, David Abrahams <dave@boost-consulting.com> 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