Documentation begets improvement. Once you write down a process, you'll quickly see if/where it needs work and what needs to be in place to help your team be more effective and efficient. Something that is written down and formalized can be iterated upon.
By making explicit the social rituals, activities, and resources that collectively comprise how the team and project get work done, we can onboard teammates quickly and efficiently so they can start getting work done right away. This also lowers the barrier to entry to involve oneself in the project.
While documenting something does require up-front time and effort, on a long enough timeline our team exerts less mental energy when common questions are answered via documentation.
Everyone appreciates structure, order and predictability, and the goal of a healthy process is to define structure so order is maintained and predictability is increased.
The core question to answer is "how do we do work?" - but the real value comes from also documenting why. There are usually several aspects to this question that can be answered, but it is worth thinking about what are the most valuable answers. Start small. A good rule of thumb is document the questions that newcomers typically ask often. Slow is okay. Steadily is imperative. The environment changes and thus the process(es) need to change, and your team can't approach this with a one-and-done mentality. Pay extra attention to questions and feedback brought up by "outsiders" - having less context is helpful when identifying barriers to entry and involvement, and the whole point in documenting our processes is to make it easy for others to get involved.
Healthy process is process that can defend itself. Every time we add process we need to be able to explain why and what benefits it brings.
There are certain more definitive aspects of a software project that absolutely should be documented:
- Where is the issue tracker?
- How does one run the tests? Is there continuous integration or deployment?
- What is the branching and merging (revision control) strategies and conventions employed in the project?
- Are there coding conventions? These are worth calling out, or even better, automating as part of your tests.
Consider documenting the following aspects of your project and team's workflow:
- Does the team meet regularly (like dailies or biweeklies)? Are there rules around these meetings (is it based on Scrum or Agile)?
- Are code reviews done?
- How often are releases made? Is there a regular cadence? Is there a specific release process?
- As was brought up in Governance, how does the team communicate? Using what channels? If multiple channels are used, what is the definitive source of truth for conversations?
Process documentation of all shapes and sizes exist. Larger projects tend to
have enshrined more rules, but some projects try to keep it as light as
possible. Larger projects tend to have dedicated web pages or documents, whereas
smaller ones might describe their process directly in their project README.md
or, if it is a bit more involved, in their CONTRIBUTING.md.
- Adobe's Open Source Office provides a starter repo with templates for many
relevant documents, such as
CONTRIBUTING.mdand issue and pull request templates (relevant for GitHub). - Adobe's Spectrum Engineering Team has a Developer Doc covering many of these points.
- The bottom part of Jenkins' Project Governance document has a "How we develop code" section.
- Thoughtbot's Playbook is a fantastic example. It starts with a light overview but goes very deep into each area.
- GitLab's Runbooks are a great example of process documentation - not for running a project, but for responding to an outage. As part of every outage retrospective, those involved reflect on what was helpful and what was lacking in the Runbook, and that feedback in turn is used to continuously improve the runbooks.