[boost] [IBD] Request for Comment, Objectives

From: Matias Capeletto (matias.capeletto_at_[hidden])
Date: 2007-07-08 10:35:50

Hello Boost,

The Improving Boost Docs project is starting to have real man power.
There are more than twelve developers right now working on different
parts of it, and we are actively trying to get more people involved.

Since we want to build a long term subcommunity which main purpose is
to continuously improve the quality of Boost documentation, we would
like that our main directives be aligned with the Boost community as a
whole.

Anticipating some recurring critics we have seen during the last two
weeks we would like to include a little FAQ before discussing our
objectives.

A) Why do we need IBD?
--------------------------------------------------------------------
We believe that documentation is a first class citizen in a project,
on par with the code. An incredible library is useless with out good
docs.
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.

B) IBD is a waste of resources, that will be better expended on new
libraries and bug fixes.
--------------------------------------------------------------------
This is an interesting critic that has pop up in a few threads. We
encourage you to check:
http://svn.boost.org/trac/boost/wiki/ImprovingBoostDocs#People
IBD is offering a place where people that is not a C++ guru (yet) has
the opportunity to collaborate with the Boost community. Working with
Boost docs will inevitably make us better C++ programmers, and augment
the possibilities to become a Boost author or help with patches.
We are not wasting Boost resources, we are getting more hands to make
Boost a better place.

C) IBD new style and resources have a less sober aspect than other
Boost resources, lowering the quality of Boost as a whole.
--------------------------------------------------------------------
We like to "enjoy quality". Our idea is that having fun and produce
quality products are orthogonal process, and since we will invest a
lot of our time at IBD we prefer to enjoy or work. We go one step
further with this and think that a happy developer produces better
quality products.

We think that this discussion is very important for the health of our
project. Your feedback will be really appreciated.

King regards
The IBD crowd

---------------------------------------------------------------------------
Here are the project objectives reproduced in the thread to
comfortably discuss each of them.

IBD objectives
http://svn.boost.org/trac/boost/wiki/ImprovingBoostDocs#Objectives

   * Build up a long term community of people that cares and constantly improve
     boost documentation and tools.

   * Achieve an unified look and feel between docs and Boost
resources, integrating them as
     much as possible.

   * Quality documentation

      - Provide correct, current and readable documentation for the
Boost C++ libraries,
        tools, environment and organization.

      - Generate Glue docs that sees boost as one tied entity, providing
        real-world examples, best practices for common tasks and
tutorials about how
        to combine Boost libraries together to build high-quality C++
applications.

      - Provide a publicly available, vendor-neutral reference manual
for the Standard C++
        library, STL concepts, data types and algorithms as part of
the Boost library
        documentation.

      - Make it easier for users to navigate through the enormous amount of
        boost documentation.

      - Use latest version of standards and support old browsers.

      - Include nice looking logos and diagrams. Although Boost
libraries are so great
        that they do not need any marketting at all, lets face it:
people are attracted
        like flies to catchy names and fancy pictures.

   * Documentation tools and support

      - Improve the docs tool chain, simplifying and integrating it
lowering the barrier
        for people willing to help us.

      - Develop tools to automate common task, and to make life easier
to boost authors.
        Docs writers should concentrate on generating content and not
on figthing with tools.

      - Work to make doc tools boost-agnostic. We believe that they
are useful beyond
        the boost community, and would welcome anyone who wishes to
use, extend or
        support them.

   * Generate formal documents about C++ documentation best practices.

   * Offer our help to libraries authors. This include translations,
proof-reading,
     proposing examples and tutorials for their libraries and helping
them with the
     docs tool chain.

   * Offer a place where not C++ experts can help the Boost community.
In general the
     tasks we do here does not involve template metaprogramming or
others complex C++
     machinery. Dessigners, artists, teachers, web experts, Python
programmers and Boost
     users are very welcome along our lines.

   * Write docs, include rationales, use our own tools. If we want to
improve boost docs,
     we should start by showcasing best practices in this project.

   * Enjoy our work. If we are not having fun while improving boost
docs something
     has gone terribly wrong.