Re: [Boost-users] A need for a COOKBOOK

From: Kirit Sælensminde (kirit.saelensminde_at_[hidden])
Date: 2007-09-22 11:13:44

Steve Toledo-Brown wrote:
> Hughes, James wrote:
> 
>> All very well asking, but writing a book is a very time consuming and
>> difficult task, then you have to get it published, otherwise you have
>> spent a year of your life with no income (or two years of your spare
>> time - and who has that any more). I'm amazed that the current docs are
>> even as good as they are.....but would agree that there is a lack of
>> consistency which I believe the boost:docs projects is aiming to fix.
>> Whether it will is anyone's guess.
>>
>> James
> 
> The "writing a book is a very time consuming" problem is to some extent 
> mitigated in the cookbook model, which Dhruva didn't really explain 
> fully. There's a website to which any user can submit recipes - 
> typically a code sample illustrating a useful technique using some 
> aspect of the technology in question for a specific purpose, with a 
> brief discussion. Some recipes are idioms, some are more like 
> mini-patterns. Over time hundreds of these recipes build up on the 
> website. Deriving a book means collecting a sample of the best/most 
> widely applicable recipes by a distributed effort. Typically you'd have 
> one reviewer per area/chapter/theme who'd choose recipes and write a 
> brief overview discussion. There's still obviously a significant 
> editorial effort involved, but it's not really like writing a book.

Given this explanation I figured that I might actually do something with 
the idea.

I'm just in the process of configuring a web site which uses our web 
application framework - which is a C++ framework that makes very heavy 
use of Boost, so we'll be eating our own dog food :) Or at least I will.

I've spend the day configuring a new site and writing some code to 
handle the bits that the site will need that fall outside of the core 
framework. The site is fairly basic, especially in how it looks. I'm not 
going to have time to do any real work on the CSS this weekend so it'll 
be just content.

The features will be a wiki page for each recipe. Categories for the 
Boost libraries that the recipe uses and history of wiki and listing 
changes. There will also be discussion forums which have a very simple 
issue tracking system on them (a thread can be marked Open or Closed if 
it describes an issue with the site or a recipe). There will also be 
some RSS and Atom feeds available from the outset.

I'll also put up some meta pages for discussing how it works and how it 
ought to work.

As I've been doing this today (Saturday) and the code we will install on 
our main server tomorrow was frozen on Thursday I'm going to put it up 
on a new live server. As the server is new and I need to test it, I 
might as well do so with this code. If nothing goes wrong with that 
there should be something running by the end of the weekend. If the new 
server doesn't work out then it will have to wait a bit until either the 
server is sorted out or we get an install window on the live server.

A final disclaimer. I personally have ambitions of getting into 
technical writing which is one reason for me doing this. My company 
wants to show of its framework which is their reason. The framework is 
not open source yet, but will be. At the moment we're having trouble 
deciding whether to use the GPL or a reciprocal license. We'd prefer the 
latter, but suspect nearly everybody else would prefer the former.

Kirit