Re: [boost] Why use Boost?

From: John Phillips (phillips_at_[hidden])
Date: 2006-02-03 15:48:32

David Maisonave wrote:
> 
> I think one of the first things that should be determine, is the boost
> doc target audience.
> Just as newspapers normally target their audience to a certain grade
> reading level, boost should also target a certain C++ programming skill
> level.
> 
> It would be hard to measure or critique a support document, if you don't
> know who you're targeting.
> 

   There are a few target audiences, and the docs should have sections 
to reflect each of them.

   From this discussion and others, one of the very important audiences 
is the group of programmers who don't yet know how much fantastic stuff 
they can find in Boost. This group will range from highly skilled C++ 
programmers who are just hearing about Boost, to people with the skills 
to use cookbook solutions, but not the skills to see how they work yet. 
The highly skilled programmers will want a concise statement of why this 
is a good solution for them and a couple of clear usage examples as a 
starting place, with the ability to drill into the details if needed. 
The people looking for a cookbook will want guided tutorials with as 
close to cut and paste applicability as possible, and the details 
suppressed.

   Another important group to remember is based on the origins of Boost. 
Since this is an attempt to establish common practice for future 
standardization, there is a need for the details to be available. This 
audience will be looking to see if this is a clearly defined approach 
with well considered abstractions and understandable implementation 
choices. For this audience, the concepts and rationale are indespensible.

   Probably, no one will always be in one of these categories. For some 
libraries I will want the details because I feel I understand the 
choices to be made and I want to examine the way this submission made 
decisions. On other libraries, I may need a solution right now to get a 
job done and not feel I have time to look at the reasons. Even my own 
documentation needs will move around in this continum. So, we need to 
have each of these pieces, and we need to have them organized in a way 
that a reader will find easy to interpret. Using names for the sections 
like "Tutorial," "Quick Start Guide," "Reference Manual," "Performance 
Issues," and "Design Issues" should guide the reader reasonably, but I'm 
  sure these names could be refined.

                        John Phillips