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

From: Matias Capeletto (matias.capeletto_at_[hidden])
Date: 2007-07-08 20:08:05

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

We have a section for this kind of formal proposals:
http://svn.boost.org/trac/boost/wiki/DocumentationBestPractices

It is empty at the moment, but we will surely add something about a suggested
section layout.

There is a precedent in Boost. Look for documentation in this page:
http://www.boost.org/more/lib_guide.htm#Guidelines

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

It is very important to note that we will not going to impose anything. If we
need to standardize something (like the use of docbook for documentation) we
will write a formal proposal and present it to the community for review.

> This could be a productive effort for the documentation community

We can offer our help to libraries authors.

> (which I will work with following GSoC).

We will be waiting for you Jake :)

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

IBD is two weeks old. Once we define our objectives we can check
others projects.
I have take a look at PHP, Python and Ubuntu docs and the content of
them is not any better than in Boost docs. The big difference is that
they have a consistent structure and style through the complete set of
docs.

In a short googling (I can not assure this) it seems that PHP and
Ubuntu are using Docbook, and Python is using LaTex.

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

Maybe in the future. Right now we must clearly define our goals and
build a solid base for the project.

Best regards
Matias

PS: How much time to the SoC end Jake? ;)