Victor A. Wagner Jr. wrote:
At Friday 2004-06-11 02:15, you wrote: I recommend the following books: read them in mostly the order listed "Accelerated C++" Andrew Koenig & Barbara Moo "The C++ Standard Library" Nicolai Josuttis --- a "must have" "Effective C++", "More Effective C++", "Effective STL" Scott Meyers "Exceptional C++", "More Exceptional C++" Herb Sutter "The C++ Programming Language" 3rd edition or later Bjarne Stroustrup "Modern C++ Design" Andrei Alexandrescu "C++ Templates" Vandevoorde & Josuttis "Standard C++ IOStreams and Locales" Langer & Kreft
Matt Austern's book "Generic Programming and the STL" is magnificent and, for me, the model of how programming books should always be written. Nothing is explained in his book before it is necessary and there is never a reference to something which occurs later in the book and hasn't already been discussed to some extent at least at a general level of understanding. The care which he took to organize the book so that it is completely understandable about a difficult subject shows on nearly every page. Good writing on computer programming is largely a problem of good organization when the writer is knowledgable in their subject matter. It is a difficult task and, unfortunately, there are few technical writers who can do it really well. Besides Mr. Austern's splendid effort, the only other technical writer I have ever read who consistently writes books at that sort of organizational level is Jeff Richter, who writes about Windows programming topics. Of course all of the writers you mention have deep knowledge of C++, but not all of them have the ability to organize their writing as well as it could be. But of the ones I have read on your list, all put out the effort to organize their knowledge as best as they could. That to me is very important.
Do we need reference documents? you betcha!! At least two kinds...one for people USING the library, another for people who will need to extend or fix the library (users _may_ not need to know the implementation details, maintenance folks will). Scott Meyers says there are two audiences for every program... I believe that includes the documentation for every program.
I would like to second your comment that their are usually two distinct audiences. A person first learning an implementation and one who is pretty good at it and who just needs to understand some of its nooks and crannies. Most of the Boost documentation is excellent, and serves the purposes of both. I am especially thinking of Mr. Gregor's documentation which addresses different audiences by having sections labelled for the level of person who is first approaching his implementations. Some of it is just bewildering to the person first trying to learn the subject at hand, even given a decent background in the area. I know the suggestion for the latter is often to spend time digging things out and then trying things out to see what the result is, but there are people like me who no matter how many things I can discover experimenting with code, still feels lost if I do not have a clear understanding of the ideas and concepts behind what I am doing.
How we present it in tutorial form, I do not know. A large problem with writing documentation post "post facto" is that the author(s) have spent _so_ much time completely immersed in the project and concepts that some very fundamental things can get left out. Parts of the project have become so ingrained that the author(s) almost cannot conceive of "the axioms" being unknown to all.
You have "hit the nail on the head" so to speak. It is easy to know something intimately, if one is the creator, and not realize that others do not have an understanding which the creator does. OTOH I understand the creator's reticence to slow down and explain things from a newbie's point of view. Unfortunately that reticence has often led to some great programming concepts going by the wayside because an audience finds it just too difficul t to understand and therefore use.
I believe it's important to have good documentation.
Bravo ! It is good to know there is someone else out there who believes that. I will go even farther. I think good documentation in the programming world is just as important as good implementation.
I'll be glad to lend assistance to any updates, though my proofreading skills seem to be far better than my writing skills.
My writing and proofreading skills are both pretty good. I will also be glad to lend assistance to anyone who asks me if I can help improve their Boost documentation as long as I can understand what they are doing. I won't write someone else's documentation for them in the sense that they don't feel that they have time to work on it themselves, which is something I can nevertheless personally understand as my own time, like most everyone else's, is limited by the needs to work and make a living.