Most agile teams have a Definition of Done (DoD). It is a checklist of things that must happen before a user story, sprint, task, body of work (etc) is considered complete. Typical checklists include peer review, passing tests, and updating the code. They also include documentation: code is documented and help documentation is updated. Yet many teams treat docs as an afterthought. They ship features and promise to write docs later. The documentation never happens – usually because of the same three avoidable mistakes (here’s the breakdown). Months later, nobody remembers how the feature works. Your DoD needs to fix that.

Why documentation belongs in your Definition of Done

Look, I’m gonna be straight with you – I used to be one of those developers who thought documentation was something you did “when you had time.” Spoiler alert: that time never came. And it bit me in the butt more times than I care to admit.

The wake-up call happened about two years ago. After a software upgrade changed where key data was stored, a downstream process relying on that data quietly broke. It went unnoticed for three years.

Three years!

I realized this would never have happened if we had a proper documentation that mapped upstream and downstream dependencies so a change in one place would trigger updates everywhere. 

The missing piece was including documentation in the DoD for that software upgrade. If we had documentation around that software, we would know what dependencies would be impacted by that software being upgraded. We would have known all of the upstream and downstream processes that also needed regression testing.

Benefits of a DoD with documentation included

A clear DoD is more than a quality gate; it is a planning tool. When teams know what is expected in terms of testing, documentation and deployments, they can accurately size backlog items and plan accordingly. Documenting as you go reduces rework and misunderstanding. It also boosts productivity and trust and putting documentation into your DoD turns good intentions into a habit.

How to include documentation in your DoD

How the heck do you actually make it happen without your team staging a revolt? Trust me, I’ve been there, and my first attempt was a complete disaster.

I made the classic mistake of going from zero to hero overnight. One Tuesday afternoon I showed up to our sprint planning with this massive documentation checklist – like 5 different required pages of different documentation including detailed integration capabilities, vendor support procedures, and configuration databases. My team was impressed and loved the idea for “someday,” but they looked at me like I’d lost my mind. And honestly? They weren’t wrong.

It was too much at once. Here’s what I learned the hard way: you gotta start small and build up gradually.

Pick three when starting out

Pick three documentation requirements max for your first attempt. I recommend starting with these because they give you the biggest bang for your buck:

1. A setup or configuration guide that gets someone to the same working state in under 30 minutes. Whether you’re deploying custom code, configuring Salesforce, or upgrading your monitoring system – document the actual steps. I’m talking about the exact button clicks, the specific configuration files, and those weird gotchas that always trip people up. This single requirement saves my team a ton of time in “how did you configure this?” questions. If writing from scratch feels heavy, start from a template – use this guide to build templates that actually scale: Confluence Templates That Scale.
2. Any integration points or dependencies. If you’re setting up a new COTS system that talks to your existing CRM, document those connection points. Same with shipping updates or new features. When you upgrade that enterprise software and suddenly the API behaves differently, write down what changed. I learned this lesson when we upgraded our offboarding system and it broke an downstream process because nobody documented the dependency.
3. One paragraph explaining why you made specific configuration choices. Something like “We enabled SSL termination at the load balancer instead of the application server because our compliance team requires centralized certificate management.” This isn’t just for custom development – it’s huge for COTS implementations too.

Does it make sense?

Here’s where it gets tricky, though. You need to actually test the documentation during your documentation process… don’t just glance at it and approve. I spend about 10 minutes per deliverable specifically testing the docs. Can someone else follow these steps and get the same result? Would our on-call person be able to troubleshoot this system at 2 AM?

One thing that really helped was creating a documentation review checklist that works for any type of work. Be it custom development, COTS configuration, system upgrades, whatever:

• Do the documented steps actually work as written? (I try to follow them myself)
• Are system dependencies and integration points clearly identified?
• Would this make sense to someone who wasn’t involved in the original implementation?
• Is there enough context to troubleshoot when things go wrong?
• Make it easy to find later – start with an intuitive space homepage so docs don’t get buried: How to Build an Intuitive Confluence Space Homepage

Follow through with documentation

When it comes to following through, you can easily make these part of your standard definition of done. If you’re using Jira, you can automate adding sub-tasks to a work item by adding the 3 pieces of documentation that you require. You can even prevent the work item from transitioning to “Done” status until the sub-tasks are completed.

The trick is making these requirements part of your actual definition of done checklist, not some separate “documentation phase.” When someone says they’ve finished configuring that new monitoring tool or completed the ERP upgrade, they should be able to check off these boxes just like they check off “system tests passing” or “stakeholder sign-off complete.”

When you get pushback

When you get pushback, and you likely will, you’re probably going to hear things like:

• “We’re not technical writers!”
• “This will kill our velocity…”
• “I didn’t sign up to write novels.”

They are not untrue statements. At first, your velocity is probably going to drop. But, skipping docs costs more. Like the time our harmless software upgrade broke downstream processes that went quietly unnoticed opening up to potential legal challenges. Whoops! It could have been avoided with having documentation of dependencies.

The fix? Make docs immediately useful to the author – so when they hand off work or go on vacation, no one calls them. Keep the bar at “functional,” not perfect. Use bullet points, screenshots, and write like you’re leaving instructions for your replacement.

Celebrate wins when docs save the day. Call out passive resistance and coach people to include context. Start with critical, complex work first. Find a “documentation champion” to help spread the habit. If adoption still lags, these five tactics will pull people into Confluence without nagging: 5 Proven Tactics to Drive Your Team into Confluence

Some will never love writing docs. That’s fine – they just need to make their work understandable to others. We all have parts of our job that we don’t particularly enjoy, but it is still part of the job. This just may be one of those items for some.

Final Aligning Thoughts

A Definition of Done without documentation is only half done. When you bake docs into the checklist, you create a culture of clarity. You plan better, reduce rework and build trust. Take a hard look at your DoD this week. If documentation isn’t there, add it. Then protect the system with a lightweight routine – run a quarterly cleanup so trust doesn’t decay (grab the checklist). Your future self will thank you.