Can documentation be agile? A field report

Corresponding services: Software documentation and Developer documentation

In software development, the keyword agile is at least as popular as DITA in technical writing. This is no surprise. Both agile and DITA focus on modularization and the requirements of the users. In this article, we discuss how agile documentation works in practice, recommend tools that support the agile processes and point out the challenges for technical writers.

What is Scrum?

Scrum is an agile methodology in software development, in which a complex product is developed in increments. Scrum teams can create products in shorter development cycles, receive prompt feedback, and incorporate changes more quickly.

Scrum is based on three basic principles: transparency, inspection, and adaption. The detailed product specification is replaced by a product backlog. A product backlog is a prioritized list of the requested features (requirements) from the user’s point of view.

Contrary to a traditional development project based on the waterfall model, Scrum teams do not assume at the beginning of a project that all of the features can be implemented. During a Scrum project, the top-priority features are implemented and finalized first. The project backlog is constantly reassessed, depending on the time and resources the teams have left. The exact scope of features in the final product is the result of this process.

The feature requirements are usually written as user stories.

During the project, the team constantly checks which of the user stories have already been implemented, which user stories should still be implemented and whether the selected implementation concepts work. If a concept turns out to be unsuitable, the project team adjusts it until it fulfils the requirements. Only when the feature is implemented, tested, and documented, the team begins to implement more features.

The Scrum Team

The core of the agile software development project is the development team. It decides which features from the product backlog it implements. Most of the team’s communication takes place in plannings and daily standups. The development team implements the features in iterations (sprints). At the end of each sprint, the product must in theory be ready for release. If the product includes end user documentation, it must be ready, too.

Challenges for Technical Writers

How do technical writers cope with the frequent changes during the product development? Can they avoid rewriting content again and again?

If the technical writers are members of the Scrum development team, they are always up-to-date. But what if they are not part of the team? Or what happens if there is only one technical writer for three development teams?

How can technical writers ever create the final documentation if the team keeps on implementing features until the last day of the sprint? And what about translation?

The agile model as such does not answer these questions. But it allows for individual solutions – as long as the basic principles are not compromised. The methods described in the following can help to avoid chaos.

Developing in Teams

Ideally, the members of the team do not change, at least for the duration of the project. This way, the team members get used to each other and the team becomes more efficient with time. The team as a group is responsible for completing the development tasks, including documentation. When planning a sprint, the team has to consider all necessary efforts to support the technical writer: provide information, give product demonstrations, or perform reviews.

The development or Scrum team should consist of a Product Owner, a Scrum Master, developers, members of Q&A, and technical writers. Depending on the organization and the type of product, more roles may be needed, for example, user interface designers.

There can be other teams in addition to the Scrum teams. Professionals from the same domain, for example, testers, technical writers, or user interface designers, communicate across Scrum teams and coordinate their work methods. We call the development teams vertical teams and the professional teams horizontal teams.

Definition of Done

An essential part of Scrum is the Definition of Done (DoD). The DoD is a checklist of all the conditions that have to be fulfilled before a user story can be completed. The documentation should be part of the DoD. That means a feature is only complete when it is also documented. However, it may not always be possible to finish the actual end user documentation in the same sprint.

To work around this problem, the team can create individual user stories for writing the end user documentation. These user stories are separated from the user stories used for implementation but are still associated with them. The original user story nevertheless has a documentation task (the so-called doc task). The developers use the doc task to write notes for the technical writers who create the end user documentation. The documentation user stories that are assigned to the technical writers are based on these doc tasks.

Scrum Meetings

Regular Scrum meetings (dailies, plannings, retrospectives) ensure that all the team members are always informed about the development status. The technical writers attend these meetings as often as possible because here they get most of the information they need. They also get in direct contact with the subject-matter experts for questions and reviews. If the technical writers cannot attend a meeting, the team should appoint a representative who passes on information.

In addition to the Scrum meetings, the technical writers have regular meetings with other technical writers (horizontal team). In these meetings, the technical writers report about their work in the project teams and discuss issues like wording, naming, structure, or layout.

Local vs. Distributed Teams

There are different ways to ensure efficient team communication. Some Scrum teams work in the same room, others communicate across time zones and continents. Technical writers have to choose: They need to be in close contact with the other technical writers but also with the members of the Scrum team. Whether they are sitting across from each other at the same desk or not is an individual decision. What matters is direct and easy communication.

User Stories

User stories make it easier to write task-based topics. They are an excellent starting point for creating the end-user documentation, even though we cannot always directly map topics to user stories as in a 1:1 relationship. Technical writers are used to look at new features from the user’s point of view. The more they are involved in writing the user stories in the backlog, the better these user stories can be used as a basis for the end user documentation.

Conclusion

At the beginning, we asked the following questions:

How do technical writers deal with the frequent changes during product development? How can they avoid having to constantly rewrite text?

Accepting change is an essential part of the agile methodology. Therefore, we cannot avoid having to rewrite text. But we can minimize the effort by applying these methods: (1) Involve user interface designers early in the development of new features. (2) Create visual concepts of the user interface, for example, using wireframes, which can then be used to write the documentation. If we furthermore assume that a feature is really completed at the end of the sprint and that the chosen concept has proven viable, we can write the final documentation before the actual implementation is finished.

If the technical writers are members of the Scrum development team, they are always up-to-date. But what if they are not part of the team? Or what happens if there is only one technical writer for three development teams?

The daily standups, product demonstrations, and backlogs enable direct communication. Feedback flows in all directions (reviews, retrospectives). As members of the Scrum teams, the technical writers can influence the design of the software and give usability advice. Right from the beginning of the project, they can answer language questions and help with the naming of user-interface elements (improve consistency).

Frequent reviews within the team ensure that all technical writers have the same level of knowledge. In an active Scrum community, it is essential to constantly evaluate the way the team works and make necessary adjustments.

Important: Being a member of many project teams and attending many meetings requires excellent time and organizational management. Quite often, one technical writer assists several development teams. The system gets out of balance as soon as the technical writer has to perform additional tasks, which prevent her or him from attending the team meetings.

How can technical writers ever create the final documentation if the team keeps on implementing features until the last day of the sprint? And what about translation?

Because the features are developed incrementally, technical writers can start early. However, they cannot describe a feature before it is nearly finished. As mentioned before, having the developers write doc tasks and moving the actual documentation tasks to the next sprint helps many Scrum teams to stay agile.

Some agile teams do such an excellent job in creating concepts for a new feature that the technical writers can write the documentation based on the concept while the feature is being implemented. To do this successfully is like playing in the premier league and should be the goal of all agile teams.

Finishing the translation in time still remains problematic. If necessary, we have to adjust the translation requirements. Modern content management systems based on XML and professional translation tools allows us to create a workflow for the incremental translation of information modules. But still, we cannot translate what has not been written yet. That is why the translation takes place at least one sprint later than the writing of the documentation. The downside of the incremental approach is that translators have to translate modules without knowing the context. This can lower the quality of the translation and affect consistency. Therefore, if there is enough time, it is legitimate to start translation at the end of the development process