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