TL;DR: teams are most effective when they share knowledge efficiently. Below are different approaches that consolidate tips from others and my own experiences.

Find out what to collect

What types of documentation does your team need?

1. Requirements

Requirements (or specifications) outline what the project needs to deliver to succeed. Every team member should be aware of the requirements for their specific work and for the entire project.

2. Constraints

Constraints are added by the team to ensure the requirements are met. They are design decisions that narrow the possible solution space of the project. If the rationale for constraints are kept track of, at later dates the team will be able to re-examine some of their assumptions and evaluate its solution. The list of constraints should be versioned.

3. Designs

Design documents describe both the overall system the project will deliver and the individual components of each system. Both the system and components can be described in terms of inputs, outputs, and dependencies. These should be owned by specific team members, and revision-controlled by date /superseded For code, this could include an API doc / Swagger

4. Implementation notes

During the implementation of each component, teams should record design rationale for why the current implementation was chosen and which constraints it was chosen to satisfy. For code, these should be with the source code as comments.

5. Tests

There should be a comprehensive plan to verify that all constraints are met. For code, this could be a TDD unit-test suite. Revisions should be tracked with same versioning as the constraints.

6. User guides

Your system will be used after the project concludes and must also be maintained. Tutorials and conceptual guides help a lot in ensuring smooth adoption of the system.

Make the process frictionless

Above all, the best documentation is the one available.

We want to collect information on design rationale process reproducability

and place it all in a common space that is

• searchable
• sorted by date
• maintains team member ownership over information

We want to collect all information useful to the project in a common space.

• Encourage quick, jotted notes while working on a project
• Jot down a summary of all actions taken and reasoning that does not immediately follow from the action while working
• Use several templates for these notes
• Track the date and edit history with the tool you use

If each team member places these notes in a searchable space, we can easily find:

• rationale for design choices made before
• fences that should not be removed
• build and configuration steps
• guardrails and testing procedures

There is a time commitment involved, but the team as a whole removes lots of stopgaps and blockers if done correctly.

The process should be fast. Besides the template and tool, everyone should feel free to contribute whichever way they feel best. Spelling and grammar except for searchable keywords should not matter.

References