At Friday 2004-06-11 02:15, you wrote:
Ok, if the Boost style documentation is too simple, and docs like Spirit are too cute, what is a nice, happy median? If we're going to demand uniformity in licensing, should we also demand more uniformity in documentation? I think a single documentation style across Boost would make it even easier to learn new libraries. I recently found it very difficult to find the information I wanted about the Boost.Test library, as well as Boost.Preprocessor. What can be done about these issues?
Dave
A "single style" for the documentation may be out of reach. I _still_ haven't figured out the concept check "system" and I find that documentation particularly inscrutable. Many years ago my father wrote me a letter about "volunteer organizations".. I'd just been elected president of an astronomy club (he was an officer of a square-dance club). What he had to say applied then, and I think here. In any such organization (and to a large extent this includes such ad hoc groups as "people using C++, boost in particular") you have the beginners (we call them newbies) and those who are attempting to "run" the organization (those who have been around for a while, and are willing to expend the effort to "make it better"). Unfortunately, this produces a conflict which can destroy the organization: the newbies want to learn "basic" stuff, the old timers (some call us the old farts) want to explore the edges and nooks and crannies and do, sometimes, very complex stuff. The same applies, IMO, to documentation. The audience is (or, if you prefer, the audiences are) very like a club. There are those who are just starting and need to learn some fundamentals (and they enjoy them). There are others who have been around the block (sometimes the planet) and need details that only a language lawyer can love (see the ISO standard for C++ for an example of the latter). Writing a single document which can serve both groups is challenge enough, but we have yet a third (and maybe fourth, fifth or...) group(s). One that leaps to mind immediately is the person that "just needs to know ....blah". They want the document to be random access and contain _all_ the relevant information at the spot _they_ choose to look. This requires that the author(s) be prescient enough to group the information in exactly the same manner as the presumed reader (unlikely doesn't begin to express the probability of _that_ happening). Yet another difficulty is in getting people to actually READ the documentation. I'm one of those weird guys that actually will read the documents/book/whathaveyou cover to cover (I'm not sure what that means w/ respect to the Spirit docs (they weren't as linear as I would have preferred)...but I read all of what I could find at the time). Hyperlinks (yes, they're useful...immensely so) exacerbate the problem. It's far too easy to get sidetracked. The reason I try to read books front to back (then Langer & Kreft come along and say "read section 2 unless you're pretty sure you've got most of it" then continue here) is because the author _generally_ has a reasonably good idea of what order to present the information. This is particularly important in such as our genre since so much of what comes later _depends_ on other things (hopefully presented earlier). Sometimes even a good author (Scott Meyers leaps to mind) discovers that he needs to refer (with a link on the CD) to items which come later in the book. What are mere mortals to do? A fine example of documentation is Nicolai's tome "The C++ STandard Library ... A Tutorial and Reference". Right on the front cover we see that there are (at least) two distinct use(r)s for this document. In facing a monumental task, Nicolai does more than an admirable job, yet he writes 799 pages (my edition) and covers _only_ (well primarily) the STL. His book is the most worn of all my C++ books, and is the only book I rate "a must have" on my recommended reading list. to wit: 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 Do not infer that I think that the STL is small, but in comparison to the boost libraries, it is. So where does that leave us (boosters)? Difficult to say. I've read the only (to my knowledge) actual _book_ about any portion of boost: the graph library and although I'm sure it's a very good book, my understanding of how to use the library still suffers. Jeremy, don't take offense, the problem is mine, I knew _nothing_ about formal graph theory when I got the book, now I know something, but not WHERE to use the library, or WHY. The book is exceptionally detailed, and likely quite good to someone who already knows graph theory. This is a fine example (from what I can tell) of documentation for "the old guys", for a newbie (in this case me) it's difficult at best. Do we need tutorials for any? some?? all??? of the libraries in boost? clearly yes for any, but likely no for all (perhaps we should use the tribool for answer here). 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. Raison d'être for some libraries? very likely. How about some background for the problem domain? I'd like one for concept-check and boost graph. This almost leads to a conclusion that something like wikipedia or planetmath will be necessary to gather all the information, since the task appears more than one _volunteer_ author could do....even for a single library in the collection. 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. Most of my above comments come from spending time (too much, likely) hanging out on IRC (Undernet #C++ channel) and attempting to help mostly newbies and _some_ (very few) very advanced people use the language (and boost). I've also been programming professionally for 39 years and have written a fair number of documents on the programs I've written (I don't write nearly as well as _any_ of the authors of the books I recommended above). I've also seen my share of poor to downright lousy documentation on programs that I've tried to use and or fix. I believe it's important to have good documentation. I've been pleased (mostly) with the documentation for stuff in boost (I don't even know for sure _all_ of what's in there any more). Does it need "fixing"? Well... I'd say the stuff _I_ can't understand certainly does, but we'll get different people saying different things are inscrutable. And authors of those sections (correctly) stating that we newbies just don't have the background to appreciate the documentation. With no pointers to _where_ such documentation exists, as far as we're concerned, the library might as well not exist. I'll be glad to lend assistance to any updates, though my proofreading skills seem to be far better than my writing skills. Victor A. Wagner Jr. http://rudbek.com The five most dangerous words in the English language: "There oughta be a law"