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.

However:

• 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

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

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

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

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.