Re: [boost] Book on Boost?

From: Bjarne Stroustrup (bs_at_[hidden])
Date: 2001-02-09 08:55:37

Kevlin Henney <kevlin_at_[hidden]> writes:
> 
> In message <00c001c09202$7b3fe9f0$0500a8c0_at_[hidden]>, David
> Abrahams <abrahams_at_[hidden]> writes
> >I think the boost book could end up being built on the documentation we have
> >for the current library set, with at least one additional chapter,
> >discussing the boost goals, process, etc... which might itself become part
> >of the website. We'd probably have to review all the documentation pretty
> >carefully, but that's not neccessarily a bad thing. Other than that (he said
> >glibly) there might not be all that much work to do.
> 
> I'm involved in a couple of book projects, and have a long relationship
> with publishers wrt technical reviewing. My experience suggests that
> "there might not be all that much work to do" are common last words :->

Famous *first* words? :-)

 
> It is possible to take a body of documentation and publish a reference
> book pretty much straight from that, but these often do not add that
> much value unless they provide something unifying that makes them feel
> like a book. For instance, Matt Austern's Generic Programming and the
> STL goes further than just the SGI docs and is a great book for many
> reasons, not least of which is its readability. Compare this with the
> Glass and Schuchert book, The STL<Primer>, which was just a printing of
> the ObjectSpace docs. Not inspiring, except in the sense that it makes
> you want to get your hands either on the more appropriate electronic
> form or on another book -- demonstrating that man pages tend to work
> better as man pages than as books :->
> 
> I think at least one additional chapter is a start, but I would see
> quite a few more, showing actual sample programs developed using Boost,
> demonstrating more than one feature at a time.
> 
> Just my USD 0.02.
> 

I've been a lurker here for a few weeks, but this may be the right spot for me 
to speak up in support of what I think I hear Kevlin say.

In my opinion, a collection of man pages is not a book. Simple reference 
information is exactly what is done well electronically. Where books can shine 
is in tutorial material and in the exposition of aims, ideas, ideals, and 
principles.

Writing is often best done if the code described can be improved as you go 
along. Once you articulate your aims, ideas, ideals, and principles, some of 
the code will look a bit less clean than it did before you started. IMO it is 
then better to fix the code (if you can) than to explain why it doesn't quite 
measure up.

Wearing my other hat as the editor of Addison-Wesley's "C++ In Depth" series, 
I'd like to encourage you to think of a short book. Decide what is important to 
say and work hard at saying it concisely and clearly. With a group effort it is 
especially hard to avoid piling on stuff. Have mercy on the reader!

        - Bjarne
Bjarne Stroustrup, http://www.research.att.com/~bs