Documentation Guidelines

Documentation is an important part of creating and maintaining a successful project.

Who

Everyone is expected to contribute to documentation. If you have the ability to edit a wiki, you can and should feel empowered to do the following:

• Add new things to it
• Edit things that could be described better
• Update things that have changed
• Eliminate things that are no longer relevant
• Congratulate each other on a documentation job well done

What

There's no exhaustive list of what should be documented, but some suggestions include:

• Processes the team should/already does follow
• How to onboard to the project
• Implementation details of what's been/is being built
• Concepts that pertain to what we’re doing
• Decisions
• Proposals

When

The best time to have written documentation is before the project started. The second best time is now.

A good rule is whenever you are asked a question, even if you ask it of yourself, the answer could be documented.

Where

Documentation should be written where it can best be discovered, which will be situationally dependent.

• Wikis for concepts, decisions and processes
• In code as comments (see language guides) for implementation details
• In issues for proposals

We will refine as time goes on, but the important thing is things get documented more than where at this point.

Why

Documentation leads to an increase in shared context, focus and happier developers.