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