September 2, 2015


Agile Documentation - An Insight

In the past decade, the migration from traditional software development methodologies (such as the Waterfall and Prototype models) to the Agile Development model has been a major game changer in the software development industry. The advantages of the Agile-driven software development process are immense. However, no rules or guidelines have been set for the documentation process in an Agile model. Many Agile key factors, such as cost optimization and effort management can be meritoriously implemented in the end-user documentation process, such as the one shown below.

The Agile Model: Challenges faced by Technical Writers

In most projects that follow the Prototype or Waterfall model, the documentation process is directly aligned to SDLC. Therefore, in an Agile environment, the alignment of documentation process to software development is quite challenging for technical writers. The major glitches that these writers have to overcome while working in Agile projects, are as follows:

  • For a GUI-based help document, documentation planning is difficult, as the requirements keep changing in every sprint of an Agile model.
  • Technical writers need an in-depth understanding of each functionality in order to prepare a document. This is difficult as each sprint is different and includes a variety of features and updates.
  • The documentation process is expected to be a parallel activity to the software development process in a sprint. However, it becomes cumbersome to update the document on the move.
  • Documentation in a traditional software development model allows the technical writer to extensively describe a product or a specific feature. On the other hand, in Agile documentation, the technical writer is expected to include just enough information in the documents that is specific to the current release.
  • Version control becomes an extremely important aspect due to frequent changes in requirements and specifications.

The Agile Model: Key Practices for Technical Writers

To avoid the above challenges, technical writers in various projects across the industry use diverse approaches. The following key practices can help writers’ produce some of the best documents in an Agile environment:

  • Participate in sprint planning: Technical writer involvement in sprint meetings and frequent scrums is essential to enhance the end-user document. Writers can get an overview of the product in the current release and, thus, can plan ahead.
  • Implement user stories: A major advantage of the Agile model is that requirements are framed in the form of user stories. Technical writers can apply these stories to track the changes in the requirements.
  • Plan smartly: If the GUI is not available, then writers can collect information, such as concept and procedures from developers and analysts. Referring to test plans and user stories also helps in preparing valid content.
  • Structure a TOC: An initial structuring of the Table of Contents (TOC) provides an overview of the entire document. The distribution of content gets easier when writers commence by structuring a TOC.
  • Keep track of changes: It is important to maintain different versions of a document in the Agile documentation process. Writers should maintain a log of issues and enhancements that were made throughout the iteration. Sometimes, a previous version of the document might be useful to describe a newly received requirement.
  • Be proactive: Technical writers should create a “Big Picture” of the target release. They can include the features that the developers are planning to make. Active participation in scrums is important to gather as much information as possible. As a technical writer, you can use color coding schemes in the sections of the document, which will help an end-user differentiate between pre-planned and actual structures.
  • Review is a must: Technical writers should ensure that the document goes through a detailed review cycle before its release. The review process should take place toward the end of the iteration, to ensure that the final draft gets reviewed. Most developers document errors and updates for their own reference, which technical writers may use during the self-review cycle of the document.

Lean Content Paradigm

Another vital principle that technical writers should implement is the Lean Content principle. Clear and concise information is the key intonation for Agile documentation. Unnecessary information and bulky documents degrade document quality. The following points describe how you can remove unnecessary content from a document:

  • If a procedure can be explained well in 10 pages, then there is no need to describe it in 20.
  • The first draft of the document should include only enough information to enable the end-user to understand the product.
  • Every section of the document should be written keeping in mind the purpose of the information and why it is relevant to a user.
  • It is not mandatory to add every detail provided by a developer. Technical writers should be able to judge what information is relevant enough to be included in the document.
  • Use tools that refine the language and provide a count of the number of words so as to cut down unnecessary content.

A crisp, formal document can not only be comprehensive, but also help in optimizing the cost of the product.


It is important for stakeholders and engineers to understand and estimate the value of end-user deliverables. A good document is one that helps the end-user execute the product at an expert level. The success of a software product that is developed using the Agile model is highly dependent on documentation quality. It is therefore essential that technical writers comprehend the Agile model and synchronize their documentation processes with the overall product development.