---
title: "How to Add Docs to Your Definition of Done"
canonical: https://supportpages.io/guides/add-docs-to-your-definition-of-done
updated: 2026-08-13
---

A documentation line in your definition of done that a reviewer can answer yes or no to, a concrete list of what counts as a user-facing change, and a route to "no documentation needed" that does not require anyone to lie.

## Before you start

Two conditions make this work. The rule has to be checkable by somebody other than the author, and there has to be a place for the writing to go. A definition-of-done item that demands an article without a template, a publishing route or an owner is a rule that generates guilt and nothing else.

![A pull request passing through a documentation gate before merging.](/images/guides/figures/add-docs-to-your-definition-of-done.webp)

*A gate on the merge cannot be deprioritised without deprioritising the merge.*

## Steps

1. **Write the rule so it has a yes or no answer.**
   "Documentation updated" is not checkable. "Any user-visible change has a new article, an updated article, or a recorded reason it needs neither" is, and a reviewer can verify all three states in seconds.

2. **Define user-facing with a list rather than a principle.**
   A new setting, a changed default, a new or reworded error message, a changed limit, a removed feature, a renamed field, a changed keyboard shortcut. Lists get applied consistently; principles get argued about in review.

3. **Put the check where the work already happens.**
   A line in the pull request template or a field on the ticket. Anything that needs a separate ritual becomes a separate meeting, and the meeting gets cancelled first.

4. **Make "no documentation needed" a first-class answer.**
   Require one line of reason, not a justification. Without a legitimate no, everybody ticks yes and the check measures nothing.

5. **Assign the draft to the author and the review to somebody else.**
   The author has the context and can write it fastest. A second reader is the only one who can see the knowledge the author assumed.

6. **Give people something to write into.**
   An article template, a named section, and someone who can publish. Most documentation that never gets written stalls at not knowing where it goes.

7. **Review the exceptions, not the compliance rate.**
   The recorded "not needed" reasons are the interesting data. Read them monthly and look for the category of change that keeps being exempted.

8. **Change the rule when the exceptions say it is wrong.**
   If internal-only refactors keep triggering the check, narrow it. A rule people route around teaches the team that the definition of done is negotiable.

## Common mistakes

**Blocking merges on documentation with no writer assigned.** The rule holds up releases for a fortnight, someone grants an exception, and the exception becomes the norm within a month.

**Wording it as "docs updated".** Updated where, by whom, to what standard? Vague wording makes the check unfalsifiable, so it is always satisfied.

**Applying it to every change.** A refactor with no user-visible effect does not need an article, and a rule that says it does trains people to tick the box without reading it.

**Measuring the tick rate.** A hundred per cent compliance on an unenforceable checkbox tells you nothing. The number of changes that shipped with a wrong article still attached is the metric that matters.

**Making it retroactive.** Applying a new rule to the existing backlog produces one enormous documentation-debt ticket that nobody opens. Start at the next change and let the backlog decay separately.

## When this stops scaling

A definition-of-done check works while a human reviews every change and that reviewer is close enough to the reader to know what changed. One team merging a handful of changes a day is comfortably inside that limit, and this is the cheapest documentation process available at that size.

It degrades once several squads merge into the same product. The reviewer no longer knows whether the article attached to a change is the only article that change invalidates, and the checkbox becomes a formality that certifies effort rather than accuracy.

There is also a structural gap the rule cannot close. A definition of done only ever looks at work someone is doing. The articles that rot are the ones nobody touched: a change to a shared component, a renamed field, a new default that quietly contradicts six pages in other sections. No checklist attached to a pull request will surface those, because nobody edited them. [SupportPages](https://supportpages.io) watches merged changes and flags the existing articles a change has made wrong, which is the half of the problem a definition of done structurally cannot reach.