Important: we have no issues whatsoever with source code documentation. This belongs to regular code audit and is kept up to date. Our problem is with developers documentation (or, "external" if you like), little blog-like tips from programmers to programmers which tend to be once written, often left behind.
We use wiki-like system to produce programmers documentation - articles wrote by programmers for programmers describing in a bit more details how particular piece of code works. Those wiki-pages usually include:
- motivations behind design decisions for parts of API (for example; we did this ugly thing because this particular 3rd party library wants stuff to be done this way, because this other library ..., because ...)
- explanation of how we deal with particular common tasks (for example; displaying trivial popup, which needs to reference appropriate application styles, register itself in registry component, and implement some interface in order to be automatically "scanned" by other component)
- good practices (subjective as it is, we do actually write this stuff down)
- environment configuration, required tools and its setup
In general, primarily stuff related to writing code that doesn't fit regular code-documentation due to its size and blog post/article-like nature.
As far as introducing this system seemed like a good idea few months ago, nowadays I feel like it's causing more problems than it solves. For example:
- people do write articles... but once code changed, wiki update rarely follows
- lot of scratch articles, wrote by somebody in hurry and left like that
- even though article-request usually comes from project lead, it's hardly ever verified for correctness/composition - which sometimes results in poor quality
The usual degradation. Code changed, wiki stays the same. Next time somebody looks for information, what he usually finds is bunch of outdated, low quality stuff - and is wondering what's going on, whether stuff that he found is accurate or (even worse) which parts of it are. And what was supposed to help, ends up doing the opposite.
At the moment it seems people are aware of the problem, project lead included, but apparently nobody seems to be bothered to do anything with it (or has more interesting stuff to do).
My initial thought was to throw it all into the oblivion (after I got bitten by outdated "tips" few times in a row), but I suppose that might be too extreme. Some information is worth noting and good read sometimes, but the problem is still the same: how you deal with its "up-to-dateness"? Have it linked to source code somehow (so when updated version of file is checked into, author of article gets notified that he might need to revise code/article)? Have designated person "watching over" it on daily basics? Do regular cleanups?