Saturday, 29 May 2010
01:05 PM
Occasionally (or frequently, depending on the exact context in which you work), the idea will be floated that the way to do API documentation is for the actual developers to include comments in the code, and then to extract these. A number of tools exist to faciliate this, including Javadoc, Doc-o-matic, GhostDoc, and Sandcastle. (Wikipedia has a long list of such tools.)
The idea is appealing in a number of ways, among them:- The developer developed the code, so they understand it best.
- When an API changes, it's easier to change comments in source code than to track down and update some document somewhere.
- That's one less technical writer you need to hire.
In my experience, tho, there's little guarantee that you'll end up with decent documentation. Here's a list of reasons why:- Most developers would rather code then write. This is all the more true, I think, when the writing consists of revising existing docs (comments) for an update.
- Is it cost-effective to have developers writing documentation at coder rates? Maybe, maybe not.
- Many developers are not strong writers, mechanically speaking -- not just spelling and grammar, but being able to articulate what it is they need to say.[1]
- Many developers (or many that I work with, anyway) are not native speakers of English (assuming the target documentation is supposed to be in English).
- Developers might not understand what the reader actually needs to know -- after all, it's generally obvious to the developer.
- Developers are often focused on details like syntax or parameter definitions, not on the reasons why a piece of code exists or why the user might need to use it.
- Developers often have a hard time grasping that the reader does not have the same knowledge that the developer does (cf The Rise and Fall of Homo Logicus).
You occasionally encounter an attitude among some developers that they have to write the docs because no technical writer could possibly understand their code. This is horse poop.
As a side issue, there's also the larger issue that API docs is to understanding a product as a dictionary is to understanding a language. Raymond Chen:There's more to documentation than dry function descriptions, people! The function description is a reference; you go there when you already know what's going on and you just need to fine-tune a detail. The real learning happens in the overviews and articles. If you want to learn how to operate your radio, you don't read the schematic first. I should add that I don't think that XML code comments are not useful. They can be part of the info (among many sources) that a tech writer uses to create docs. In individual instances where the various issues raised above are not issues, using developer-generated documentation for APIs (when used with additional material) will work just fine.
A final note: XML code comments can become the initial drafts that are fed into a community-supported doc effort. That can work. A limitation here, tho, is that improvements made by the community tend not to go back into the doc comments.
[categories]
writing
|
link
|