How do you keep your documentation updated ?

Question

We all know the importance of documentation right? I'm working with a fairly big team of developers, and we keep all the documentation together in a wiki. So far so good.

The other day I had a look and everything was totally outdated. After some inquiries i found out that it was basically because of:

• Documentation writing allergy.
• Oh crap! i knew i forgot something!
• bah! who cares.

I'm talking about big projects here, involving servers, web services, distributed systems and such. So, I'm pretty serious when i say that you need documentation to understand what's going on.

How do you convince people/make them understand of the importance of having a nice, up to date documentation? what are your experiences?

Answer 1

You have to make documentation more than a second-class citizen. This means that releases aren't ready until the code is documented, and projects and milestones can't be completed or reached without proper documentation.

Once you have a deadline missed because someone didn't document properly (even if their code/deliverable is finished), it will be driven home more to your team that documentation matters.

Answer 2

can't you enforce documentation as part of Quality Control to have:

• Data Flow Diagram for the end to end solution
• each vendor is obliged to present documentation in order to get a sign-off
• Release Documents for every change

Answer 3

If documentation is important to the overall success of the project, it should be included as a project deliverable. Add SPECIFIC documentation tasks to your project plan or sprint and make sure it gets done.

Of course, documentation tends to be one of the first things to fall out of project scope due to time constraints, etc, but if it is important you'll find ways to make everyone accountable for these deliverables.

I think what you are doing with the Wiki is a good move. Making documentation accessible (lowering the barrier) helps a bit.

Not to completely rain on your parade, however, I've never found a team which kept up with documentation unless there was a person like a technical business analysist who was 100% allocated to the task. Otherwise, documentation slips. That said, if there's a way to eliminate or reduce the need for detailed documentation you are far better off.

Answer 4

What type of documentation is being required? Perhaps it's not being done because it serves no real purpose other than to satisfy some arbitrary whim. If the developers are commenting check ins to your source repository and the classes/methods/properties are named in such a way that their purpose is immediately obvious what additional documentation are your developers being required to provide?

I've worked too many places that required reams of documentation that went into a binder and sat on a shelf until they were eventually tossed. After 2 release cycles most of it was irrelevant and the things that weren't were things that the CODE should have been able to provide.

Answer 5

If you have some kind of build process in place, like continuous integration, you could have that build fail if (at least) the auto-generation of documentation (like javadoc/phpdoc/doxygen) fails or reports problems.
(And send a mail to the whole team about it ; no-one likes being the breaking the build ^^ )

That obviously only works for javadoc and the like... But that's a start ; and I've noticed that many developpers (includin myself :-( ) don't maintain that as much as they should...

At work, I'm currently working on a project with developpers in several cities ; we have a wiki in which we post stuff... And we noticed the same kind of problem you are reporting...

One thing we did to help with that is that now, when someone creates/updates a wiki-entry, he speaks about it on the IRC channel we all are.
This way, other developpers know there's been an update, they know there is an entry about that stuff, and they often go check it out.

It is more motivating to know people will go read the documentation you've written than telling to yourself "why would I take time to write documentation when no-one ever reads it?"

Another way is to considered an outdated/wrong documentation entry as a bug, and report it and track it alongside other bugs in the application (using the same bugtracker that is used for any other bug).

It will make those problems notices -- and no-one wants to have bugs in parts of the application/documentation he is responsible of ;-)

Unfortunatly, just saying "we need an up to date" documentation is never enough...

Documentation has to be considered as one part of the project, the same way the code or the GUI is. And that means treating it like a real part of the project!

Answer 6

First of all, the codebase:

• No code goes into repo without documentation (and tests). This is enforced by having an open development enviroment and the requirement of a peer-review of every patch that will be commited. (dedicated (for the day) committer will commit patches into tree, automated testing starts after each commit, automatically rolls back to working state after patch fail.) (added plus: smaller, more frequent and higher quality patches because they want to help the reviewer and get their patch in, and in addition let all tests pass)

secondly, server configuration changes:

• Every configuration change needs to be documented in such way that it can be implemented by a peer on the staging server.
• After that, a crash recovery scenario will be executed by our secretary, and it is tested if she can successfully restore it.
• explicit checks will be done both times to confirm if the changes were successfully implemented.

Answer 7

Code I find easiest to work with tends to be "self-documenting."

If:

• your variables and methods are well named
• your methods are less than ~50 lines, and
• all your lines each do a single comprehensible thing
• non-trivial statements are commented inline

then documentation is often superfluous. The code is the documentation. Want to understand how a class/method works? Read the code.

Write Code; think English.

Answer 8

The problem with documentation getting outdated is that only the couple of people who really work on a part of the project that changes or isn't documented know that the documentation is lacking. These people might be under time pressure and will assure you that it will get updated, or that the documentation is sufficient, even complete. There's no easy way to detect this failure until someone discovers it by needing documentation. Often this is only when those people are no longer available or can no longer recall the project.

The only work around here is to keep a log of work done with descriptions of how it affect future use of code. THEN you can check the documentation changes against this log to see if they reflect the logged changes. It's not simple, nor foolproof, but it helps, and it can jog the memory of the errant doc writer.

Answer 9

Have you tried Doxygen ... ?

A colleague of mine created a .Net Wrapper for it called Doxygen.NET (which is LGPL licensed)

EDIT;

Ohh yeah, you can find Doxygen.NET here; http://code.google.com/p/doxygen-net/

And a sample of it in use here; http://ra-ajax.org/Docs.aspx

Have fun :)

Answer 10

In our company we use three systems to do our documentation and keep it upd to date. The first one is DokuWiki to edit the documentation. But to keep all of this up to date we basically use Doqua - an Eclipse plugin (all our projects are Java based).

Doqua helps to keep high quality standards concerning the layout and linking and so on. In addition it has a tagging system with tags that can run out of date. So the tagged documents will have to be reviewed from time to time - the system tells us when.

Our automated build system (Hudson) also has a copy of Doqua and checks the documentation regularly - at least when there is a new version to be released. It also fetches the current version of our documentation from the DokuWiki using the Site Export plugin and does a check-in into our svn repository.

Unless there are any errors in the documentation we do our release. If not we don't.

I think that documentation can be integrated into the production cycle using some free tools. And all of our developers are involved.