4 Tips To Improve Documentation in Software Engineering Teams
There are a lot of nebulous problems in communication inside organizations.
To progress with documentation efforts:
- Focus on essential but small projects for the organization.
- Start small with something that you can nail.
- Solve the documentation issue around a single internal project in the Engineering organization.
- Define a simple outline to follow and assign a point of contact to track execution and progress.
To expand the documentation, define top-level categories in a wiki or standard knowledge management system. e.g., Project documentation, Operations documentation, Playbooks, Monitoring Information, Best Practices, and Style Guides.
Schedule a weekly standing meeting to keep track of the progress along all the stages. The Agile Manifesto suggests working software because code is an objective measure of progress. Yet, the onboarding process requires formal documentation to ramp up people to the team’s culture faster — working software over comprehensive documentation. Writing code is more productive, but documentation about the team’s past and decisions is equally important.
An Architecture Decision Record (ADR) is a short document that describes a team decision that influences the software architecture they are building.
The result is a collection of approved, rejected, or superseded ADRs in a decision log. It includes the decision but also its context and consequences. Any team member who identifies a decision like that should create an ADR. Templates can simplify ADR creation and ensure it captures all the relevant information. The team member who completes an ADR is also its owner and is responsible for maintaining and communicating its content. Initially, the ADR owner provides an ADR in the “proposed” state, which means it is ready for review.
The owner should wait for the team’s review and decide if the ADR is accepted, requested for rework, or rejected.
If the team finds that the ADR needs improvement, it preserves the “proposed” state, and the owner and other team members work on the refinements. Otherwise, the ADR status changes to “accepted” or “rejected,” and the ADR becomes immutable. If the team needs to update that decision, the team should propose a new ADR, and when this ADR is accepted, it supersedes the previous. Design documents describe the decisions and tradeoffs you’ve made in specific projects. They are like Architecture Decision Records, but the stakeholder reach is broader and only sometimes technical.
Write design documents for any project whose capabilities will be used by many future projects.
Write design documents for projects that impact your users. Write a design document for any work that takes more than a full sprint of engineering time to complete. Good design documents describe specific problems. Explore possible solutions and explain the selected approach in detail. Writing a good paper and getting it in front of others is better than delaying for something better.
Design documents act as the backbone of an Engineering organization’s Technical Strategy. Thus reducing the decision fatigue that every new project brings to software engineering teams.
