Writing Software Documentation in Agile “Scrum” Teams

Home/Publications/CIDM Matters / eNews/Information Management News 01.08/Writing Software Documentation in Agile “Scrum” Teams

*** This article also appears in STC TAC Magazine. ***

Pietro Margutti , Freelance

“Agile” or “lightweight” techniques are becoming more and more popular for developing new and innovative software projects. In these new contexts, the ways technical documentation is developed have changed quite remarkably. It can be interesting to understand reasons and consequences for these new working scenarios.

New techniques in software development

Traditional models, based on the so-called “waterfall” paradigm, have been proven not to suit the needs of the software industry, where constantly improving technology demands high flexibility and imposes rapid changes of direction. In fact, the waterfall approach, very successful in manufacturing processes, prescribes a perfect sequence of development steps—requirements, analysis, design, implementation, documentation, and tests. This technique is effective only when the phases remain stable and predictable during the entire process. Errors and modifications would cause unexpected and costly backward steps.

In software development, and possibly in other technology-driven applications, new ideas from marketing need to be evaluated within the latest technology framework. Therefore, specifications and analyses cannot remain stable, as they need to be re-discussed if they are to prove their value when applied to emerging technologies.

Non-agile, heavyweight waterfall processes are rather slow, impose a rigid separation of roles, discourage cooperation across departments, and might even foster conflicts between teams, e.g. between marketing and technical departments, or between development and testing groups (technical communicators always try to make peace, don’t we?).

That is why, starting from the mid-1990s, new agile methods have been proposed that make use of more iterative and incremental processes to develop software.

In 2001, the Agile Manifesto1 presented principles of the new approach:

  • Humans and interactions instead of processes and tools
  • Workable software instead of extensive documentation (that is, fast prototyping; don’t worry, tech writers, there’s still a lot for us to do!)
  • Cooperation with the customer instead of contract negotiations
  • Reactions to changes instead of following a rigid plan

Agile Methods and the Scrum Method

The Agile method consists of various methodologies. Among them, the Scrum approach was initially described in 19862, when it was noted that small, highly interactive, and cross-functional teams can perform very well working as a unit, like a scrum formation in rugby.

In the early 1990s, the Scrum method was successfully applied in various projects in the USA3 and quickly became quite popular. The Scrum method is based on the following rules:

  • A scrum team is typically made up of five to nine people, including a Scrum Master, various development and test engineers, and at least one technical writer.
  • The requirements are collected in a prioritized product backlog by a product owner.
  • Development is organized in short iterations called sprints during which a selected set of the highest-priority requirements are meant to be completed.
  • Sprints are planned in detail and last a few weeks—typically one month—to deliver a working (and documented!) product release on a regular basis.
  • During the sprint, the Scrum team works in close cooperation and meets every day (daily scrum) to discuss and resolve any problems.
  • The online and/or printed documentation released at the end of each sprint, although preliminary, should be usable by anybody working with the software.

New tasks and opportunities for technical writers

At least one technical writer is part of each scrum team and follows the development of the product right from the start. This is great news. I think we’ve all suffered in the traditional “waterfall” approach from the fact that we didn’t become involved until very late in the product development process. We used to struggle to understand what everything was about and then hurry to document the final product with no chance whatsoever of intelligently contributing to the development activities.

With Scrum, the role of technical writers as part of the development group, can be remarkably more important. In addition to the actual product documentation (our classic user manuals), our experience can support developers and testers in delivering better project documentation, i.e., software analysis and design papers.

Also, technical writers can interact with developers and provide important comments about usability and ease of use of the software. Many of us have found that functions that are difficult to document actually need to be reengineered before we can produce any documentation for them!

Activity planning and tracking is very detailed during the sprints, and precise estimates for all documentation tasks are required. Planning forces technical writers, as well as all other team members, to improve their estimation skills.

New technical abilities may be required beyond the classic professional capabilities of technical writers. For example, it could be useful to acquire a basic knowledge of the UML standard, used for diagrams in all modern software specifications. Also, depending on the software project, specific knowledge of new software standards and techniques can also be useful. We need to develop sufficient skills to actively follow the daily meeting with software specialists and to interact with them effectively.

New tasks also mean more people required. In general, projects based on the Scrum approach normally require more technical writing resources than non-Scrum projects. A project previously staffed with two technical writers might very well need three or even four. New job opportunities can therefore be expected.

Difficulties: A cultural clash and needs of new technical skills

Working in a scrum team can be quite a change for most technical writers. If you like to work at home, quietly, and in perfect solitude, then scrum is not for you, as it requires continuous interactions with the team and daily meetings.

In new scrum teams, a cultural clash may occur at the very beginning, when we have to meet every single day with software developers and testers. In certain cases, these engineers may initially not like us, regarding us as a kind of alien on the team and possibly even neglect the importance of our documentation tasks altogether.

Typically, however, cooperating daily to achieve a common goal helps to develop harmony and sympathy among the members of the small team. Despite possible initial difficulties, we should make an effort to contribute to the team with all our experience and competence.

As our primary task, we must ensure that the documentation tasks are properly defined at the beginning of each sprint and then proceed to complete these tasks. Additionally, we should be willing to help beyond our normal duties: for example, we may proofread a software specification, draw or check a complex UML diagram, or help write a project report, and so on. Remember that the scrum team can only win or lose as a whole.

Note that, unlike previous techniques, the product documentation is developed from the bottom up, following the releases of the monthly sprints. Each iteration is supposed to deliver a complete, although possibly minimal product, including documentation. While staying focused on the individual features being released, we should use our experience to keep in mind the big picture, i.e., the global documentation targets.


The Scrum methodology can result in extraordinary performances in a creative, lively, and empathetic environment. To contribute to making that happen, we need to commit to the team, learn with humbleness, and teach with respect and understanding.

In other words, as in rugby, we need to push forward as strongly as we can and, at the same time, contribute to the team’s coordination, which is essential to ensure that the Scrum moves on harmoniously and eventually wins the game.


1 http://www.agilemanifesto.org.

2 “The New Product Development Game” by Hirotaka Takeuchi and Ikujiro Nonaka, inThe Harvard Business Review, Jan-Feb 1986.

3 Agile Software Development with SCRUM by Ken Schwaber and Mike Beedle, Prentice Hall, 2001.

More about Scrum can be found at http://www.scrumalliance.org. See also the article “Adapting Challenges and Strategies to Scrum” in STC’s Intercom dated July/August 2007.