API documentation tasks should be played like any other story by a development team. They should be identified, sized, prioritised, worked on and reviewed. Engineers should lead the initial drafts of writing content pages. It should be done collaboratively with the product managers and Documentarians. The product managers own the sign-off required to move a documentation task to ‘Done’. I will call this approach Docs Are Tasks Too (DTT).
What does DTT mean practically ?
- Evaluate: During Sprint Planning, each development team should consider if a story requires API documentation. Teams can make a note on the on the Jira ticket to indicate whether or not a development story requires API Docs content.
- Create Jira task: If the development task needs documentation on the developer portal, create a Jira task for the documentation work.
- The task should be on the team’s board or backlog
- Relate the story to the documentation task using the Jira ‘Link Issue’ feature. Use the ‘Depends on’ relation to make it clear that it’s a dependency.
- Provide a brief description of what documentation is required if you can. If you are in a hurry, it’s also OK to just leave it as a stub Jira with a title but no description. At least it’s a placeholder for a future conversation on what needs to be done.
- Place the task in the same sprint as the development story.
- Label: Give the documentation task a label, for example ‘API-Docs’. This enables makes it easy to create a Jira filter to view all API Docs tasks on the project.
- Estimate: Give the task a story point estimate. This helps keep the tasks specific and small. Break up larger tasks into smaller ones.
What happens after the Jira tasks have been created ?
The documentarian can review the team boards during standups, and see what doc tasks are outstanding. He can discuss with the product managers on what level of documentation is required for the task, where the documentation should live, and who can start working on it.
Why DTT is important
It enables the team to:
- Identify what documentation needs to be written for a piece of development work.
- Make it visible to the entire team
- Assign someone to work on it
- Try and coordinate the release of the documentation with the release of the software.
- Avoid ‘Documentation-Debt’ . (Yes, like Technical Debt, but for documentation).
A DTT approach will help scale the production of content for developer portals.