Andrew Hundt wrote:
I have to say Boost's documentation is generally excellent.
I would say that the quality of the boost documentation is all over the place. I'm going to divide my observations into Reference Documentation and Narative or Tutorial Documentation. Reference Documentation. ================= Excellent examples Fusion MPL Iostreams I'm sure there are others. These pages have a regularity which which suggests they can be filled in almost by "form filling" or by an automatic tool such as DOxygen. It looked to me that DOxygen might be configured to do it but it looked like a lot of work. Also these libraries share a strong, clear and formal set of "Concepts" (Type contraints) in the SGI/C++ standard manner. This makes the generation of good documentation more automatic. Also note that these examples include a small example to show the function, class, or template is used. This in theory is not strictly necessary, but very, very helpful in practice. These examples also share a clear classification of concepts, classes, functions, macros, etc. Bad Examples ========= Units - no documented type requirements Numeric Conversion - information might be in there - but since it doesn't follow conventional layout I can't find it. Everything else ========== There are other good and bad examples and most libraries follow between these two examples. One big problem is that the customary way of making reference documentation for templates is only really well described in the SGI website. http://www.sgi.com/tech/stl/ The C++ standard has information on this - but as usual it's border line unreadable. Narative or Tutorial Documentation ======================== As has been mentioned, it's very difficult to prescribe what this aspect of the documentation should contain due to the wide variety of scope, and scale of the various libraries. Clearly something like spirit can't be expected to teach the whole theory of parsing. And something like BOOST_FOR_EACH doesn't need much of an explanation at all. Never the less... Excellent examples. ============= Spirit - an amazing tutorial on parsing. One can actually enjoy reading this even if you don't use the library. Beautifully crafted graphics as well. enable_if - a very weird and unintuitive concept pretty well explained. Bad Examples ========= Units - there are lot's of specific examples which are very helpful, but no "tutorial which builds up from something simple. Certain important things like "system" are barely touched upon. Random - very well designed library (which I believe is now part of the standard) but reading the documentation it took me forever to figure out that there are really two more or less orthogonal pieces - generator and "distributors" and what the role of each is. I'm sure a better tutorial would have helped. Everything else ========== of course everything else is somewhere in between. This makes very hard to make more general statements. I used as examples only those libraries I've spend enough time with to actually use in some other program so don't feel disappointed (or relieved) if your library isn't mentioned above. Also I don't want talk about this or that libray - they are only examples for the general discussion. Summary ====== I've already pointed to my more extensive thoughts on the subject and I don't want to test the indulgence of the viewers here with the details. I'll boil it down to a couple of points. a) Make reference documentation which looks like that of the SGI website. Write this while you're writing your library. b) Write a couple of tutorial examples while your writing your library. c) By the time you are ready to submit your library for review, you should be able to write a short tutorial. Take the view that you need to "sell" the library. Motivation and walk through of a simple but useful example so the reader cat "get the idea" in 15 minutes. Thanks for indulging me - I trying hard not to rant. Robert Ramey