Boost logo

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


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk