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

From: Jake Voytko (jakevoytko_at_[hidden])
Date: 2007-07-08 12:17:20

On 7/8/07, Matias Capeletto <matias.capeletto_at_[hidden]> wrote:
>
> 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.

To add to Matias' description: Since Matias is attempting to draw non-C++ers
into the community through the Boost Docs project, I think that being
ostensibly professional, yet fun would do a lot to draw in individuals. This
is not unprecedented in the OSS community in the least. Go to the Ubuntu
main page for example.. the first thing you see is a diverse group of people
who have clearly been blown backwards onto the floor from the level of fun
they experienced while using Ubuntu. Ubuntu has had quite a bit of success
and attention, so emulating some of what they do could be prudent.

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

I think that consistency should also be a goal of the documentation (better
to make changes now than when Boost has 500 libraries and has turned
sentient). Using your Boost.Bimap documentation as an example (which is
actually the most remarkable library documentation I've ever seen, so I'm
glad that you are heading this initiative), adding a "One Minute Tutorial",
"Reference", "Performance", "Compiler", etc. section to all libraries will
help people find what they need a lot faster.

This is just an idea, though.. I'm not asking all library authors to revisit
libraries they wrote 5 years ago and redo the documentation. This could be a
productive effort for the documentation community (which I will work with
following GSoC). All of the current Boost documentation show their authors'
biases towards what useful documentation is: some focus on hand-holding for
beginners, others speak more heavily in the language of the C++ standard.
Beginners / people who aren't interested in the finer details can just go to
the "One Minute Tutorial" section and be on their way, and coders who really
like to know what's going on, and know all the options, can go to the
reference section

>       - 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.

Have you considered contacting projects with an existing documentation
system (PHP, Python, Ubuntu, etc..) and ask for recommendations/advice?

>    * 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.

I think you'll get a few more offers for help if you were to make it clear
to the outside world that you are looking for help. Getting the
documentation effort added to the "Participation" section on the front page
could be one way to do this.

Jake