“Working software over comprehensive documentation”

= The Manifesto for Agile Software Development

Agile software development is most notable for its emphasis on delivering functional product to the customer on an early and continuous basis as its primary goal, with documentation as a secondary priority. Today most organizations have worked to better incorporate technical writers into their Agile process but based on the process itself and its founding principles, there’s often a modified role for the technical writer. A big reason for this is that technical writers often do most of their work toward the end of the sprint after the changes are completed by the development team. For the first part of the sprint, technical writers are usually finalizing the previous sprint’s documentation updates. Another reason is that technical writer resources are sometimes too scarce to have a writer for each scrum team.

Technical writers are often part of 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. This article is based on my experience working on a large development team where, over time, we developed a sort of hybrid role for the technical writer in terms of their roles and requirements within the Agile framework. The large software development project was comprised of five to seven different feature teams (aka scrum teams), and each technical writer was a member of 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, but if that’s not the case, then here are some helpful tips.

First Week of Sprint

The first week of the sprint is very different for a technical writer compared to a developer. By nature, the technical writer is usually cleaning 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. However, starting work on those, aside from the administrative tasking, is often done toward the end of the sprint when the release is close to being finalized. Bottom line: get used to playing catch-up.

Meetings

Scrums

The scrum (or daily stand-up) meeting is a short (15 minute), timeboxed meeting that is usually devoted to the developers. The primary goal of scrum is to review what has been done in the last 24 hours and what will be done 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 scrum as an observer and to note any changes to the sprint backlog.

If a technical writer is working with multiple sprint teams, it’s important to choose what meetings to attend, especially when it comes to scrums. We found that attending two or three scrums per week was sufficient for technical writers. Some of the key things that a technical writer needs to accomplish in scrums are:

• Ensure that the scrum team is including the 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 will need to 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.

Ideally, a technical writer is dedicated to one sprint team, but when that’s not the case, then attend scrums regularly as it fits your schedule. Be sure to attend when you 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 should attend 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.

Here’s some of meetings that were not required for technical writers based on my experience:

• 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:

The following are examples of common tasks technical writers must complete as part of each sprint:

• Release notes:
  • 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 the release is finalized, 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, do all the relevant screen captures and update all user documentation.
• Official system documentation updates (technical SOPs (for example, SA SOP, DBA SOP), policy, security, and configuration documentation, etc.):
  • In my experience, we had a 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 where the primary goal is the rapid release of functional product and user documentation. Additionally, those documents had to go 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 always was working on its own schedule to complete scheduled reviews and updates.
• Application requirements (feature requirements, software requirements, business requirements, etc.):
  • Requirement updates should be done on a continuous basis, but not finalized in the requirements repository until after the release. In my experience, additions, updates, or deletions were done in DOORs and assigned to a release number, which were given a status of final after the release.
  • Requirements, like system documentation updates, can deprioritized to accommodate essential sprint documentation.
• Use cases
  • Use cases, like system documentation updates, can be deprioritized to accommodate essential sprint documentation. In my experience, use case updates were the lowest priority item in our suite of sprint documentation.

Conclusion

When working in an Agile environment it’s essential that a technical writer is, well, agile, as you will often have to juggle working with different teams; however, it’s also important to establish routines and milestones. 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.