I work on a relatively large project (~570 KLOC) in a relatively small team (formerly 5 developers, now 2). Large amounts of code can appear and then vanish in months; for example, a few years ago an investment bank launched a new stock exchange, then shut it down 7 months later—thousands of LOC were written to support that exchange's interface, then deleted.
To help operations and support teams as well as new developers, we have an internal wiki (a modified DokuWiki, if it matters) with things like retrospective specs (we're writing specs as we go, unfortunately) and what various settings, flags, and status codes mean and do.
Due to the fast pace of development, however, much of our wiki content becomes obsolete in months, if not weeks. And it's not as simple as updating a single wiki section about whatever component is being changed; with numerous interlocking components, changing one thing, like a setting in the algorithmic trading component, might require looking through a hundred references to this setting and/or component in the wiki, many whose sections may need updating.
The main issue, I believe, is a motivational one. Developers know that whatever they write has a good chance of becoming obsolete soon, so it's rarely worth it (nor is it practical) to go searching throuh the wiki to update all relevant pieces, especially when 2 or 3 days later there might be a request to change, say, the format of a setting, or even its functionality. This leads to distrust of the wiki—even amongst ourselves, we're never sure whether what we're reading indeed describes the latest functionality. And that, I feel, ultimately feeds a vicious cycle akin to the broken windows theory: the perception of disorder demotivates any action to bring back order.
My idea was to migrate the wiki to something more like Stack Exchange—for example customizing Question2Answer. For two reasons:
I hope that putting all information in Q&A form encourages documentation to be written with the thought in mind, "What question am I trying to answer? Who am I trying to help?" This is unrelated to this post, though.
More importantly, my idea is to use tags—a tag for each component, each setting, each business term, etc.—so that it's easier to find posts that need updating, rather than going through every instance of a keyword—and keyword searches are context-less already, on their own.
Before I go through with this idea, though, I thought I might benefit from advice if anyone else has worked in such a context. I'm open to all ideas and alternatives!
How do you keep highly cross-referenced documentation up-to-date in a rapidly changing project?