Writing software documentation in agile “Scrum” teams

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 has changed quite remarkably. It can be interesting to understand reasons and consequences of 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 results in being 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 new 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 Manifesto [1] was published to show the principles of the new approach:

• Humans and Interactions instead of processes and tools
• Workable Software instead of extensive project (internal) documentation
• 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 definition comprises various methodologies. Among them, the Scrum approach was initially described in 1986 [2], when it was noted how small, highly-interactive, and cross-functional teams can perform very well working as a unit, like a scrum formation in rugby.

In the early 1990’s, the Scrum method was successfully applied in various projects in the USA [3] 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 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– in order 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) in order 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 corresponding 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 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. This 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 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 means 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 in order 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 writing a project report, etc. 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.

Conclusions

The Scrum methodology can provide 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.

References

[1] www.agilemanifesto.org

[2] The New New Product Development Game by Hirotaka Takeuchi and Ikujiro Nonaka, in Harvard Business Review, Jan-Feb 1986

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