Lacking sufficient documentation creates inefficiencies in our day-to-day work supporting and enhancing our systems. We lean on the same individuals over and over to support a particular feature or have repetitive conversations to onboard new team members or implementation partners. This also delays project initiation as we struggle to backfill how the feature works resulting in costly delays and increased pressure on delivery schedules.
Good documentation should be:
Easy to find – Any Technology member should be able to access the content.
Clear – Technical and non-technical audience.
Succinct – We’re not paid by the word... and sometimes pictures say it better.
Scannable – We’re all busy. Consistent structure (detailed below) will help speed up consumption.
Searchable - Use meaningful keywords as you write so it is discoverable via search.
Managers will likely encounter friction on this topic. Documentation is typically the last, and most expendable item on the list of priorities during a project. In order to avoid this pitfall, it must be considered as part of your Definition of Done for each and every story.
We are also looking for a consolidated picture of how something works. A never ending transaction log of work items implemented will be very time consuming to digest in order to distill the current state. If a transaction log is desirable, it can be an addendum to the parent document.
Pro Tip: AI tools do a fantastic job of summarizing kickoff, refinement, and knowledge sharing sessions. Putting those tools to work for you will further ease the “burden” of creating useful documentation.
The following describes the structure of documentation we are looking to capture for each functional area. Documentation is the responsibility of everybody, and while there is a logical owner to some of it based on Agile roles, this does not mean we defer responsibility for that content to someone else if it needs to be created; there is shared responsibility.
Description: A brief statement on what object or functional element is being addressed with this document. Often, the content can be sourced from project kickoff materials, or story refinement sessions.
Description: Functional explanation of how the end users interact with the feature. This is important to give the context for the feature to aid in future evolution or deprecation conversations. The “user story statement” is a good place to start for this piece of the document.
Notes:
This information can be plugged into testing and training materials in later phases of its lifecycle.
Process flow and swimlane diagrams are highly valuable in this area.
Be sure to note how the experience differs for different personas.
Description: Technical and architectural details on how the object or feature was implemented. We are looking to build a consolidated view of how something works, so each story should update the current state of the object/feature.
Notes:
High level architectural designs are a good foundation for this content, but should be extended with more implementation design info.
Some objects or features have multiple logical subsections, so we can break up the documentation into separate pages to make it easier to consume.
Consider using standard (UML) technical documentation when appropriate, e.g., ERD, class diagrams, etc.
Flagging dependencies with other objects and processes is critical for us to be able to safely modify functionality in the future and track regression issues. When possible, provide links to other documentation when it is related.
Description: Document known situations that need to be managed (like a manual process) or can be a list of support tickets that have come up and how they were resolved. In this way, our documentation can be used as a maintenance run book.
Description: A place to capture functional and technical ideas for evolution of this feature. We don’t have infinite time to implement the perfect design, or all the project “nice to haves”. This section can be a place to capture thoughts on how this area can evolve.
In the Knowledge Base (KB) area, identify the existing documentation for this feature or create a new document if it does not exist.
Add the documentation location link to the story.
For projects, top-level KB documentation area(s) should be added to the Iteration Zero presentation for all team members to reference.
In the issue tracking system, add a field for a link to the documentation.
Documentation review should be part of “Definition of Done.”
Peer review
Story testing/closure review
If the issue is so small or trivial that it does not require any updates to documentation:
Reference existing documentation area on the ticket and comment that no documentation is necessary (decision to be confirmed during peer and story review).
Create the core content on that page:
“What is it?”
“How is it used?”
This content is primarily for Technology team members familiar with our application, so keep it simple and to the point.
“How does it work?”
Consider linking to additional pages if this content is substantial.
“How do we support it?”
This can be a combination of expected maintenance activities or real-world issues that have occurred within this area.
Like in the “How it works?” section, create sub-pages if there is going to be a lot of content in this area (we can always move content to subpages later if you are not sure) and link to it under this section.
“In the Future…” (if necessary).
Project closeout (formal activity)
Migrate any remaining project assets to the KB area.
Share KB documentation with the larger team to raise awareness of the new state of the system.