Fueling standard C++ docs
It would be nice to have a proposal about how we will tackle the Standard C++ Library Boosted documentation.
Someone will have to jump in to start it, and get others involved.
This is something from a private conversation with Andrew Sutton, to start thinking about how we will do it.
Andrew wrote:
I think, along these lines, there are two sub-projects (well, more like three). The first is to determine if boosters are interested in contributing to a new doc-only library (libs/std) or something like that. Second, we need a number of different prototypes on how to actually present the documentation. This is a content and presentation issue. Third, is to try to sell that standard to other libraries so that concept docs become more pervasive.
Lets see how things evolve in the next days.
Tags:
community,
std boosted docs
3 comments:
I think that if it ever gets fleshed out with proper multi-browser support, the Unified Look and Feel http://tinyurl.com/38l6e6 would be perfect for the visualization side of the project. It has a few immediate advantages:
1) It will already have been debugged
2) It looks fantastic
3) It will allow Boost libraries to more easily become integrated into the C++ Standard, if they are the kind of libraries destined for such things.
As far as the actual content goes, I think we may want to split the documentation for each header into two discrete segments: reference, and best practices. Everyone and their grandmother has written a C++ book that teaches the elements of programming, and I'm sure some have done it better than we ever can. Authors like Meyers and the Gang of Four (Thanks again, Matias!) pick it up for intermediate and advanced users. The things I most frequently have questions with are either syntactical or very technical in nature, and I feel would be the biggest help to the widest variety of programmers
I could see why maintaining standard C++ library documentation as proposed would benefit Boost greatly. One, it would likely become the (or one of the) standard library documentation sites, and would immediately raise awareness of Boost to just about any C++ programmer out there. Two, it would be easier (and more visually / format-wise consistent) to cross-reference Boost with STL docs where appropriate. Three, when things move from Boost to the standard, it's really easy to move the docs. And due to the numerous relationships between Boost and the standard library, it would be justifiable to maintain a good, user friendly version of its docs.
One thing I'm not sure about is priority - it seems like the first step for IBD should be to get all of Boost documentation ducks in a row, before tackling something like
documenting all of the standard library. I would guess that all the tools developed to make writing/converting Boost docs as easy as possible (templates, etc.) would significantly reduce the required work to document the standard library, so seems like waiting until at least the IBD tools and guidelines settle might be a good thing. Prototypes would indeed be useful - but if the assumption is that the Boost doc format and the standard library docs format are the same, then the prototypes might be done for Boost libs instead (again, a question of priority).
Perhaps we should throw out one or two small parts of the standard library on the 'docs to be converted' list, so people doing the conversions can take up whatever task they prefer / feel is more important.
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.
Post a Comment