Improving Boost Docs

Fueling standard C++ docs

2007-07-14T14:56:00.000-07:00

It would be nice to have a proposal about how we will tackle the Standard C++ Library Boosted documentation.
Someone will have to jump in to start it, and get others involved.

This is something from a private conversation with Andrew Sutton, to start thinking about how we will do it.

Andrew wrote:
I think, along these lines, there are two sub-projects (well, more like three). The first is to determine if boosters are interested in contributing to a new doc-only library (libs/std) or something like that. Second, we need a number of different prototypes on how to actually present the documentation. This is a content and presentation issue. Third, is to try to sell that standard to other libraries so that concept docs become more pervasive.

Lets see how things evolve in the next days.

Bouncing Ideas

2007-07-10T17:48:00.000-07:00

IBD community,

These are suggestions that are more or less taken from a post to the Boost Development forums a few days ago.

I feel that it would be helpful if there was a little bit of standardization in the layout/content of the documentation. A lot of the documentation implements similar ideas (one minute tutorials, introductions, reference sections), but each individual libraries documentation has the earmarks of the authors.

What could we do in the way of standardization? If we had a list of common sections for all libraries, it would be easy for all users to find what they need. Just looking for a quick reference? Go to the "One Minute Tutorial" section. Looking for the reference? Reference section. Rationale? Rationale section.

Does anyone have any thoughts on this?

Sorry for the delay.. I had a personal commitment bite me from behind, and Joaquín, who had been busy for a few weeks, gave me a laundry list of suggestions/changes for my GSoC project ;)

IBD at iGoogle

2007-07-09T17:01:00.000-07:00

I am using iGoogle as my home page. If you are using it too, you can add two widgets to aid your work in the IBD project.

The first one is Enhanced Bookmarks, to quick access IBD resources. Playing a little with it you can get something that looks like the new style. Remember that we are trying to have an unified look and feel over all our docs and resources. ;)
Here is a picture of it:

The second widget is a RSS reader for the project news. I have used CustomRSS to be able to tweak it. This is how it looks:

Here is a snapshot with both widgets.

smart_ptr translation progress

2007-07-06T14:39:00.000-07:00

I've just committed the latest changes to the conversion of smart_ptr docs to quickbook, it's in boost_docs/trunk/libs/smart_ptr in the sandbox. The translated docs now include a rough version of all of the class template docs. Most of the hyperlinks need to be revised (except in scoped_array, which has been translated more or less completely), and there are a few more miscellaneous pages that I haven't started translating yet.

The source builds OK with the CVS HEAD + patches that fetch the .css from the project root. Sorry I haven't switched to the newest boost docs build files... I'm bad I know :-( Will do that soon.

The CSS conversion tool made this so much easier - thanks Rene and Matias.

Private conversations

2007-07-05T18:53:00.000-07:00

A few of us have been talking about the objectives of the project and crafting new ideas to improve Boost documentation in private mails conversations.
I will try to summarize some of the conclusions in this blog, so other people can comment on them. Others members of the IBD community will probably do the same.
Stjepan has just become blogger, and it will not be long until others jump in.

Behind the scenes

2007-07-05T08:10:00.000-07:00

The idea of this Blog is to have a medium where to leave a record of the things that happens in the Improving Boost Docs project. We will tell you what is going on behind the scenes and what are our next objectives. The idea is to do informal posting here. The formal face of the project will be our Wiki page at Boost Trac.

This is a community blog, if you are part of the project I really encourage you to become a blogger. Send me a mail and I will give you the needed permissions.

June is over. It has been a busy month, and we are heading towards and exciting July.
Thanks to all the amazing folks that are involved in the project.
Lets make IBD a reality!