These are some tips that I use when working on documentation for current projects like Penny.
- Think of the audience.
- Describe the big picture and then drill down as you go. In creating a feature, 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. It’s best to have a single copy and link to it from the design document you are working on.
- Keep it as short and to the point as possible using only the most relevant information.
- Find a balance between no documentation and too much.
- Maintain documentation and keep 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.
Follow me on