Summary
As a part of a recent discussion about strategy on The C++ Source within the Editorial Panel, I mooted my taxonomy of documentation, and claimed to be good at some aspects, and not others. This having raised eyebrows, I am keen to learn more of the wider world experience ...

As far as I can tell, Documentation is classically seen as one of two things:

• The stuff you write in big officially signed-off documents, pertaining to a piece of work performed for your client / employer. It is primarily aimed at system users and maintainers
• The stuff you write in HTML/PDF form that accompanies your open-source software. It is primarily aimed at users.

To my mind, both of these kinds of things fall into the class of things that developers don't like to do. Obviously, the first one tends to be done more rigorously and professionally than the second in general, since more tends to ride on its being effected well. (Or, at least, more immediate and tangible things, anyway.)

In our discussions I suggested that documentation is actually a wider and more diverse thing, and comprises the following categorisations:

1. Client Documentation. This is the stuff you write about your work work, aimed at system users and system maintainers. It typically includes project specifications, design documentation (UML and whatnot), deployment guidelines, etc. etc. It also, importantly, includes the act of passing on information on a person-to-person basis, such as when walking developers on your team, or of your client, through the implementation, and assisting them in joining or taking over the (part of the) project.
2. Library Documentation. (This covers both open-source activities and libraries that you might build/enhance as part of your work for client/employer, on which I expound below.)
3. Pedagogical Publications. This is the stuff that we crazed few who actually mix real work with writing articles, columns and books spend too much of our time doing.

Being taxonomically obsessed - largely to relieve the headaches I get with my personal technological future shock - I suggested a further breakdown of the second main type of documentation, as follows:

1. "Written Documentation". This is the classic stuff, being written text (usually in HTML/PDF) and discussing, for each particular library/component/API/class the aims, restrictions, targets, example code snippets, etc.
2. Sample Programs. As often as not, people learn libraries from sample code, and good sample code can teach a lot and engage potential users in one's library. Bad sample code can have the opposite effect: I've recently learned that I've been guilty of this with at least one of my libraries, Open-RJ - see here and here. This caused me to expand the samples to include, for the C-API and the C++ and STL mappings, a cut-to-the-bone example, showing minimal simple use of the libraries, in addition to the existing full-featured program that shows the full range of behaviour.
3. Component Interfaces. The actual component interfaces are an extremely important part of the documentation: the code is the documentation. Bertrand Meyers makes the point that this applies to consistency across libraries just as it does to individual components within them. I'm doubtful that any developer would disagree with this notion, but maintaining such consistency is a significant task.

In the discussion, I volunteered that I'm probably adequate at 1 and 3 but, for open-source libraries, am pretty sketchy at 2.a and, despite (humbly ...) being reasonably good at 2.c, also decidedly ordinary at 2.b. Another Ed Panel member questioned whether anyone who purports (or at least attempts) to be a decent author of technical articles and books could do so if they're bad at documentation. My feeling is that they can, albeit the reason might be expediency/sloth rather than an inate disjunction of abilities. Naturally, that's based on my own rather up-and-down status in this regard, mixed with my arrogance in assuming that I could be good at 2.a if I decided to put in the appropriate effort; I may well be wrong.

The question I seek to promote discussion on is whether developers must indeed be good at all forms - except 3 - to be considered successful (or at least competent) as a professional engineer. I'm also very interested to hear about projects that have had good success despite being lacking in one or more facets of their documentation.

Thanks in advance

P.S. If anyone out there is feeling altruistic, or has a college project on apply semi-automated tools to documentation, or some such, the STLSoft documentation is in sore need of improvement. :-)

Talk Back!

Have an opinion? Readers have already posted 15 comments about this weblog entry. Why not add yours?

RSS Feed

If you'd like to be notified whenever Matthew Wilson adds a new entry to his weblog, subscribe to his RSS feed.

Digg | del.icio.us | Reddit

About the Blogger

Matthew Wilson is a software development consultant and creator of the FastFormat, Pantheios and STLSoft libraries. He is author of the books Imperfect C++ (Addison-Wesley, October 2004) and Extended STL, volume 1 (Addison-Wesley, 2007), and is currently working on his third, Breaking Up The Monolith: Advanced C++ Design Without Compromise. He has published over 60 articles on C++ and other topics, and has served as columnist and contributing editor for C/C++ Users Journal. Matthew believes that code should be discoverable and largely self-documenting, and lives up to that by being a hopeless documentor. He can be contacted via http://www.imperfectcplusplus.com/ or stlsoft@gmail.com.