Sorry for quoting Andrew's entire post below, but I really want to endorse it. I consider myself very demanding when it comes to documentation quality, but he's thinking about this at a level beyond where I've been. I agree 100% with the direction in which he's headed and would happily follow him into battle. It's sort of a relief to know he's taken up this cause because now I know I don't have to worry (much) about it ;-)
on Fri Jul 20 2007, Andrew Sutton <asutton-AT-cs.kent.edu> wrote: >> Wow! Great Andrew... this can really fuel the standard docs project. > > Yes... There was much rapid typing, and opening of files. Now, my > wrists hurt, but never before have so many empty files been committed > to such a great cause :) > >> We have been informally discussing the fate of the Standard C++ >> Library Boosted Documentation in our community blog. >> >> Jake and Stjepan have made some very important points. >> One in particular was a revelation for me: > > I read those this morning... > >> We should move further discussion here. > > We could, but I actually prefer the mailing list since this > discussion is fairly on-topic. I'm going to pick on something Jake > (Voytko) said: > > "I think we may want to split the documentation for each header into > two discrete segments: reference, and best practices" > > This is mostly in the right direction, except that there's a little > more to it. Many libraries require or provide concept documentation. > Concise, well-organized, and well-presented concepts are going to be > critical for C++ developers - more so in the future than now, perhaps. > > I would also like to make a distinction between "reference documents" > and "code-listings". There are a number of libraries that sell their > API reference material as a simple listing of header files, classes, > and functions (a la Doxygen). This is a lazy way to write docs and > isn't any better than looking at the header file. Reference documents > should have a complete (textual) description of the the function's > behaviors, its parameters, its preconditions and postconditions (if > relevant), return values, and exceptions. > > And then there's the examples... Each reference doc should contain a > meaningful example that illustrates best-practice use of the API. And > what I mean by "meaningul" is that examples should draw from a real > problem as much as possible. Here's the SGI example of std::vector: > > vector<int> V; > V.insert(V.begin(), 3); > assert(V.size() == 1 && V.capacity() >= 1 && V[0] == 3); > > This is one of the most egregious examples I've ever read. There are > roughly 25 methods in this class and the example shows 5 - and none > of them are very useful. Giving meaningful real-world examples helps > the reader connect with the material since it's showing the > usefulness of the subject in a relevant way. A good example of using > a vector might be the creation of a histogram (counting observations) > since it would rely on the random access properties provided by the > vector. > > Examples of _bad practice_ could follow the "good example". These > might illustrate things like iterator invalidation. We could also > have "snippets" that show the best way to perform common tasks (like > erasing a range of elements). > > MSDN actually does a pretty good job with reference docs. That should > probably serve as the model. > > I'll re-post this as a comment on the blog-site just in case. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com The Astoria Seminar ==> http://www.astoriaseminar.com ------------------------------------------------------------------------- This SF.net email is sponsored by: Splunk Inc. Still grepping through log files to find problems? Stop. Now Search log events and configuration files using AJAX and a browser. Download your FREE copy of Splunk now >> http://get.splunk.com/ _______________________________________________ Boost-docs mailing list [email protected] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
