The problem with contributing documentation to projects

March 28, 2011

Every so often, a well intentioned person will suggest that you should help out open source projects by contributing documentation (there are several variants of how this suggestion is made, but this is what all of them boil down to). The problem is that this is much harder to do than you might think, especially for significant technical documentation like API details.

Setting aside all of the other difficulties of creating documentation, the core issue is that official documentation must above all be accurate. It is not enough to describe something that works (for you); you need to be correct about what you are describing and how it operates, you need to be complete, and you need to be describing the correct way to do something (instead of, say, an odd hackish workaround that you stumbled over or an internal interface). In order to produce this sort of accurate documentation, you generally need to be an expert with a deep understanding of the code, the history, and the philosophy of the project.

(An additional issue is that you generally need to be an expert with the current bleeding edge development version, because this is generally what the project is working on. Any expertise with older released versions is much less useful; even if the project is going to maintain them for some time, projects are generally not enthused about having older versions be better documented than new ones.)

Trying to contribute documentation that is not necessarily accurate is just as dangerous as other overly-detailed bug reports and patches, and for the same reasons. At a minimum, you force a project expert to double-check your documentation (and even for an expert this may take work and investigation). At the worst, your inaccurate work is good enough to fool people on superficial examination and is accepted into the project's documentation, where its subtle problems may fester for some time.

By contrast, carrying on on a blog to note down some things you've worked out is much easier. You don't need to be complete, and no one with any sense expects a third-party blog entry to be accurate in the way that the official documentation is.

Written on 28 March 2011.
« Some thinking on proliferating web standards
Why you should avoid 'from module import whatever' »

Page tools: View Source.
Search:
Login: Password:

Last modified: Mon Mar 28 00:38:29 2011
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.