Technical writing in a multi-team Agile environment tends to be a game of catch-up. Agile software development emphasizes delivering functional products to the customer early and continuously as its primary goal, with documentation a secondary priority. Today most organizations incorporate technical writers into their Agile process better than in the past, but based on the process itself and its founding principles, technical writers often play a modified role.
The role of technical writers in an agile environment
Technical writers often perform most of their work toward the end of the sprint after the development team completes changes. During the first part of the sprint, technical writers finalize the previous sprint’s documentation updates. Technical writer resources are sometimes too scarce to have a writer for each scrum team.
Technical writers often participate in several Agile scrum teams, so it can be confusing to determine the role and level of participation needed by a writer working in an Agile/scrum environment. I wrote this article based on my experience working on a large development team where, over time, we developed a sort of hybrid role for the technical writers in terms of their roles and requirements within the Agile framework.
Our large software development project consisted of five to seven different feature teams (aka scrum teams), and each technical writer participated in two or three feature teams during any given sprint. In addition to the feature teams, the technical writer was part of the documentation team and other teams, such as the management team. Ideally, a technical writer is assigned to one sprint team and has the time to participate in all the scrums and sprint meetings. If that’s not the case, here are some helpful tips.
First Week of Sprint
Technical writers experience the first week of a sprint differently from developers. By nature, a technical writer tends to clean up outstanding updates as opposed to creating new ones. Based on sprint planning meetings, the writer should know the majority of documentation updates needed for the next sprint. Aside from the administrative tasks, they don’t often start working on those until the end of the sprint when the release is almost finalized. Bottom line: Get used to playing catch-up.
The scrum (or daily stand-up) meeting is a short (15-minute), time-boxed meeting, usually devoted to the developers. The primary goals of a scrum include reviewing accomplishments over the last 24 hours and determining tasks to finish in the next 24 hours. That often does not apply to the technical writer or documentation, especially early in the sprint, so the technical writer often attends a scrum as an observer and notes any changes to the sprint backlog.
Writers need to understand which meetings (specifically scrums) they must attend, especially when working with multiple sprint teams. We found that writers don’t usually need to attend more than two or three per week.
Key accomplishments for writers in scrums:
- Ensure the scrum team includes sprint documentation tasks in its sprint board.
- Review sprint documentation tasks and report if there are any questions, action items required, or impediments.
- Update the release notes draft based on any changes to the sprint backlog.
- Make note of any requirements changes (new features, screen changes, business logic, etc.).
- Determine what documentation must be updated, such as help files, user guides, software requirements, use cases, etc.
- Make note of the general progress of the sprint.
- Remind everyone of review deadlines for sprint documentation, if applicable.
In an ideal world, technical writers only work with one sprint team. In the real world, they attend scrums as regularly as they can, especially if they need to report impediments or ask questions.
Additional Sprint Meetings
Guidance on attending other sprint meetings is a little less murky than it is for scums. Generally, the technical writer attends all sprint planning meetings for their assigned teams. Beyond that, most meetings are optional or not required aside from the sprint retrospective, which should be attended by either a senior writer or a writer designated to provide input (what went well, what can be improved, etc.) from the documentation team.
Based on my experience, technical writers do not need to attend these meetings:
- Sprint Review (demo)
- Backlog Grooming
- Any changes here will be reflected in the scrums that the technical writer attends.
- Scrum of Scrums
- This might be attended by a senior writer or designated writer representing the documentation group like the retrospective.
- Release Planning
- Go/No Go
- Again, this might be attended by a senior writer or designated writer representing the documentation group like the retrospective.
Sprint Tasking and Tips for Technical Writers
Technical writers must complete the following as part of each sprint:
- Keep the list of sprint tickets for all teams updated in the release notes draft.
- Write the release notes ahead of time. This means keeping an updated release notes draft throughout the sprint with all the tickets in the release.
- When finalizing the release, add any necessary details or descriptions, then convert it to your deliverable format.
User guides and help files
- Update help files and user documentation in the last week.
- Toward the end of the sprint, generally after tickets have passed testing and you’re sure the application changes are final, grab all relevant screen captures and update all user documentation.
Official system documentation updates
Examples include: technical SOPs (for example, SA SOP, DBA SOP), policy, security, and configuration documentation.
- We used our two-week window following the sprint to complete our official documentation updates for changes directly related to the sprint, which is typical in an Agile environment. Additionally, those documents went through a formal review/sign-off process, so it often took extra time to get the reviews and required approvals before publication, and when the corresponding sprint ticket could be closed. Additionally, our official system documentation was on a continuous update schedule, so the documentation team worked on its own schedule to complete scheduled reviews and updates.
Examples include feature requirements, software requirements, and business requirements.
- Requirement updates should be done on a continuous basis, but not finalized in the requirements repository until after the release.
- Deprioritizing requirements like system documentation updates helps accommodate essential sprint documentation.
- Use case updates often become the lowest priority in sprint documentation. Deprioritize them to accommodate essential spring documentation.
Technical writing in a multi-team Agile environment demands, well, agility, as you often must juggle working with different teams. However, establishing routines and milestones remains important. For example, even though you aren’t attending all the scrums, try to attend on the same day of the week so your schedule is as planned out as possible. The same goes for milestones. These can be weekly or based on the release status. Try to complete sprint documentation on the same timetable for each release and make processes repeatable.
Our technical writers and instructional designers excel at working in agile environments. Contact us today to learn how we can help you create your important documents faster than you can in-house, while maintaining high quality and saving you money!