How do you keep reference documentation up to date?

Question

I'm doing Yet Another PHP Framework for the fun and sport of it, and I'm doing the first rounds of documentation. I'm planning to code a little, document what I've coded, code some more, adjust the documents to reflect the code's new abilities, repeat. For example, the configuration is pretty manual and tedious at the moment, but I'm documenting it as it needs to be configured as it is today. Once I get as far as automating the setup, I'm planning on rewriting those parts, to reflect the current status.

What I'm wondering, are there any heuristics to keeping the reference documentation up-to-date? I'm not just talking about documenting the API (which kind of comes for free with PHPDoc and the likes), but also the greater scheme; the tutorials, overview-articles—everything. Are there any good ways to minimize the chance to forget to update something special?

Answer 1

This is a very difficult problem because of delocalization: The information in one documentation element may depend or affect multiple code locations, and when you are viewing the code location you are typically not aware of the documentation. Thus, a change in the code may not trigger an update of the documentation, even if the user would have been willing to do it.

I think it is important to include some form of explicit links with each code section in which a change would trigger a change in the documentation. It's a stretch to get people to update the text, so getting them to find the areas that could be affected is difficult, especially for more general materials (e.g., an API)

If I am updating a feature that is mentioned in several locations, I need that list to at least have an idea for where to look for a potential need to update.

Answer 2

We have done something similar in my first job.

/*
<document>
    <version>x.y.z.g</version>
    <date>10.4.2009</version>
    <key>fff#ggg</key>
    <more...................../more>
</socument>
*/
int ggg(char x){
...
...
}

The documenter app would test the dates difference (and in later versions, against our source control) and would raise a warning flag when it suspected a mismatch.

In PHP, it shouldn't be too hard to build something to scan code remarks, if they are kept in a pre-known, convenient format.