- Think of the audience.
- Describe big picture and then drill down as you go. In creating a features, describe the feature and what you expect it to do. Then break it down in components, describe those components and drill down further if necessary. Finally describe the look, maybe even include some concept art.
- Use plenty of diagrams and examples.
- No duplicate text. Best to have a single copy and link to it from the design document you are working on.
- Keep as short and to the point as possible. Sticking to the idea of only the most relevant information should be included.
- Find a balance between no documentation and too much.
- Maintain documentation keeping up to date as the project progresses. Two ways that I have used on current projects is either a change log in the document or version control.
- Everyone on the team should have input.
- Add a glossary.
These are some tips that I use working on documentation for current projects for projects like Penny.