Four agile development practices that benefit the documentation

I work with a team of 30+ developers and QA on a large platform. For the most part, I write the documentation by reverse engineering a feature and acting as its first external consumer. This is a good way of sanity checking design and architecture as well as learning how something works.


  • Code does not always capture intent. Why something was designed a certain way – especially if deadlines mean that you have to opt for a minimum viable solution – makes a huge difference to the documentation.
  • Code tells you nothing about business requirements and the delineation between features is not always obvious.
  • Not all work results in code – for example, scalability testing might results in a set of  recommended practices.

Here are four development practices that can benefit the documentation. In our organisation, these are either enforced by the tools or the project manager.

A task for everything, and for everything a task

 to do list GIF
Source: Giphy

Every piece of work must be captured as a product backlog item (PBI), task, or bug in the project tracking system (such as JIRA or Microsoft TFS).

  • The developers cannot start a piece of work until a task exists
  • All tasks are related to a specific feature area
  • All commits and pull request must be linked to a task – this is enforced in the UI

This creates a comprehensive paper trail and links every code change to a task with a title and a description. The writer can use the task list as a starting point for the documentation and feel confident that it accurately reflects the work that was done.

Detailed descriptions and acceptance criteria

Beeld en Geluid Labs work office busy openbeelden GIF
Source: Giphy

Acceptance criteria are used by QA to plan tests, and is usually a very detailed list of expected behaviour – e.g. “If you try to save an object with a special character in the title, you will get a NoSpecialCharactersException”.

The most useful descriptions contain business requirement and any key decisions that were made – particularly if they were made during an offline meeting

Detailed descriptions and acceptance criteria tell you how a feature is expected to work and where the requirement came from. It is the best place to get business context for a task if you cannot speak to the developer or product owner.

Unit and integration tests

 test cooking american dad testing expected GIF
Source: Giphy

Unit and integration tests are a great way to see the acceptance criteria in action, and are a virtual gold mine for code samples. Use tests to get a sense of how a feature or an API should be used.

Tip: If your team uses SpecFlow, test scenarios are defined in a very easy-to-read format.

Tag breaking changes

@SummerBreak food summer crush break GIF
Source: Giphy

This practice is particularly useful for release notes and for updating documentation that has already been written. Whenever a task or bug results in a breaking change to existing documentation, it gets a [breaking changes] tag.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s