What is the most useful *project* documentation that you've encountered?

Question

I have a big problem with keeping documentation up to date, especially since the underlying infrastructure of my application undergoes many changes during the early stages of development.

I find it's very difficult to document a moving target. However, this can make things a little difficult for new developers who are just coming on to the project, since all of the documentation is invariably only half correct.

Given that I'm already failing to document everything, I've decided it's probably best to just document the most important features of my project.

My question really is:

• What are the qualities of a useful document that will help a developer come up to speed on a new project and allow them to quickly begin making valuable contributions?

How long should it be? What sort of information was included? What level of detail? What sort of UML?

Note: I'm not interested in links to examples of good API documentation. Presumably the average developer can read and understand code.

Answer 1

To answer the bolded question.

I think functional documentation is the best. Don't say anything about what is under the hood. Simply explain what the program does. Once the programmer understands the domain s/he will have a better context under which to evaluate the abstractions that were made in the code.

Joel has a series on functional specs that you can take a look at.

Answer 2

We have a document called "Requirements Validation"

This document is the higher level overview of a feature and contains:

• Business Requirements Overview
• Functionality Overview
  • Wireframes of new UI elements / Changes
    • Every page that is going to change should have a wireframe outlining the changes and highlights to any new interactive elements
  • Business Rules to take into consideration for non UI elements.

This document is usually delivered before the official spec and is used for the initial breakdown of work. It allows us to have a high level overview of everything required for the new feature and we can start thinking of edge cases and spec gaps early.