It's one thing to explain a design to other people who are already familiar with the topic (but not intimately so), but explaining how to use a functional language interpreter to someone whose programming expertise has been on-the-fly gawk scripting...
of both the language and the interpreter has to become far more elegant than if I were explaining it to another person with my background. (Just
"Brian Allison" <brian@dtmr.com> wrote in message news:<43E353BC.8060807@dtmr.com>... the design try
explaining to someone who's used to Perl/gawk why the new script language has no variables.)
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.
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
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.
This is the reason why I would argue for decoupling the "user guide"/ "tutorial"/"cookbook" content from the reference information. Library maintainers should focus on the reference information, the user perspective can be persued by others. I think the role of documentation manager would be more in the form of coordination, editing and gentle reminders, than tech stuff. Nigel
John Phillips wrote:
The people looking for a cookbook will want guided tutorials with as close to cut and paste applicability as possible, and the details suppressed.
I wonder if it would be a good idea to write a C++ tutorial that incorporates Boost from the ground up. Teach dynamic memory? Teach smart pointers along with it. And so on. I'm personally convinced that the standard library should be taught as a part of the C++ language itself (i.e. don't even attempt to teach C-style strings until you're through with pointer principles; instead teach std::string), and given the nature of many Boost libraries, this just seems like a natural extension of that principle. Sebastian Redl
Sebastian Redl wrote:
I wonder if it would be a good idea to write a C++ tutorial that incorporates Boost from the ground up. Teach dynamic memory? Teach smart pointers along with it. And so on. I'm personally convinced that the standard library should be taught as a part of the C++ language itself (i.e. don't even attempt to teach C-style strings until you're through with pointer principles; instead teach std::string), and given the nature of many Boost libraries, this just seems like a natural extension of that principle.
Sebastian Redl
This sounds more like a book than a part of the online documentation. It could be a pretty good book, if done well, but it is still a book. John
participants (5)
-
David Maisonave -
John Phillips -
John Phillips -
Nigel Stewart -
Sebastian Redl