Do you make awesome documentation?
There are a few styles of documentation:
Bad Example – Old School
The old school way is document first – lots of planning, and lots of heavy documentation created upfront before even a single line of code is written.
This is the method most familiar to teams who are comfortable with Waterfall and have possibly never heard of Agile. Documentation can normally be characterized by:
- Heavy, long documents
- Sequence Diagrams
This is a well-established way to do documentation, but it has several problems:
- Gets out of date quickly
- High maintenance overhead
- Needs a business analyst
There may be exceptions – some situations benefit from this kind of documentation; for example, it may be necessary to support a business case – although a well-defined spec is a better document to support a business case.
Tip: Documentation should be as minimal as possible. If your circumstances require this style of documentation, start by limiting it to just enough to cover your first couple of Sprints. And recognize that by going down this path you make a commitment to keeping it up-to-date.
Good example – The 8 Important Documents
This style of documentation is used by modern teams who are Agile only.
In the repository (for developers):
1. README.md – Explains the overview of the project and provides links to the rest of the documentation. It is important for the README.md to show a high-level architecture diagram that illustrates the overarching solution.
2. docs\Instructions-Compile.md – Instructions on how to build and run the project (AKA the F5 experience).
3. docs\Instructions-Deployment.md – Explains how to deploy the solution, including any additional processes (e.g. DevOps)
4. docs\Business – explains the purpose of the application, including the problem, goals, and statement of intent.
5. docs\Technologies-and-Architecture – Provides a technical overview of the solution.
- An architecture diagram which outlines a high-level overview of the project.
- Lower level architecture diagrams of the system eg. Azure resources diagram (auto generated)
- Coding patterns followed (e.g. Clean Architecture)
- 3rd party libraries used
- 3rd party services used
6. docs\Alterative-Solutions-Considered – explains other options that were discounted. For example
- We chose to use a code-centric .NET solution over a low code solution because we did not want to be locked into any specific vendor eg. Dynamics, Outsystems.
- We chose to use Angular over React because 5/6 developers on the project were more familiar with Angular.
- We chose to use Azure over on-premises to avoid procurement of costly servers.
- Note: If you decide that after the fact that the chosen solution is wrong, this should be explained. Include what led to the current circumstances and if there is a planned change.
7. docs\Definition-of-Done - Ensures that your team maintains a high level of quality with a Definition of Done
8. docs\Definition-of-Ready – Ensures that all your PBIs are well defined to an agreed standard before adding them to a sprint (see https://rules.ssw.com.au/have-a-definition-of-ready)
Keeping these documents in the repository means that you ensure that any documentation the developers need to work on or run the code is where they need it - with the code.
It also means that when a developer makes a change to the code that needs an update to the documentation, the documentation changes can be checked in along with the code in the same commit.
Exposing documentation through a Wiki (for developers and other stakeholders):
Documents to be read or edited by the Product Owner (or other members of the Scrum team) should be exposed through a Wiki. The advantage of this approach is that the writing experience in the Wiki is more friendly for non-developers. The Wiki should be sourced from the repo docs\ folder to ensure documentation is kept up-to-date. There are several options for creating a Wiki:
Azure DevOps wiki options:
- Wiki edited via the repo (recommended)
- Wiki edited via the portal
- An alternative Wiki platform (e.g. Confluence)
GitHub wiki options:
- Markdown files edited via the repo (recommended)
- The GitHub repo Wiki
- An alternative Wiki platform (e.g. Confluence)
Tip : You can publish your documentation from the repo using GitHub Pages
Tip : All of your documents (in your Wiki and your repository) should be written in Markdown (see https://rules.ssw.com.au/using-markdown-to-store-your-content)
Tip: Use your documentation for onboarding developers
Tip: Keep your documentation as minimal as possible - automate the F5 experience and deployment process (documents 2 and 3) using PowerShell scripts. Then your documents can just say "run these scripts"
The rest of the jigsaw
Scrum Tip: Update your Acceptance Criteria - If you use a policy that requires commits to be linked to PBIs, then you understand that the PBI is now the documentation. If requirements change (based on a conversation with the Product Owner of course) then the PBI should be updated.
When updating the Acceptance Criteria,
strike through the altered Acceptance Criteria, and add the new ones. Get the PO to confirm your understanding.
Enter search text, click ‘Google’, and see the results populate below.
Enter search text and automatically see the results populate below.
This should be added to the Definition of Done.
What's "Technical Debt"?
During a project, when you add functionality, you have a choice:
One way is quick but messy - it will make further changes harder in the future (i.e. quick and dirty).
The other way is cleaner – it will make changes easier to do in the future but will take longer to put in place.
'Technical Debt' is a metaphor to help us think about this problem. In this metaphor (often mentioned during Scrum software projects), doing things the quick and dirty way gives us a 'technical debt', which will have to be fixed later. Like financial debt, the technical debt incurs interest payments - in the form of the extra effort that we must do in future development.
We can choose to continue paying the interest, or we can pay the debt in full by redoing the piece of work in a cleaner way.
The same principle is true with documentation. Using the 'old school' method will leave you with a build-up of documentation that you will need to keep up to date as the project evolves.
Warning: if you want to follow Scrum and have zero technical debt, then you must throw away all documentation at the end of each sprint. If you do want to keep it, make sure you add it to your definition of done to keep it updated.