Sponsored Link •
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:
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:
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:
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. :-)
|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 email@example.com.|