Skip to main content Skip to main navigation Skip to search Skip to footer
Type to Search Subscribe View Tags

HCL Technologies

User Documentation in an Agile Development Environment

User Documentation in an Agile Development Environment
Harinder Sehgal | April 15, 2011

The key principle of agile development is to develop robust software with nominal expenditure and investment. The development life cycles should usually be of 2 – 3 weeks, in which a particular piece of software is developed, tested, and documented. Figure 1 shows the difference between efforts required to develop documentation in SDLC with that of Agile methodology.

In the Agile development environment, many companies create their own Agile methods while using some of the original ideas and principles defined in the Agile Manifesto (

Usability Engineering Lifecycle Activities

Figure 1*: SDLC Vs. Agile development

Terms Used in Agile Development

The basic terms associated with the Agile development environment are:

  • Iteration: A tenure during which the software is programmed, at the end of which the Quality Assurance (QA) testers verify that the software is working as expected.
  • Stand-up: Daily meetings in which the progress of the development work is shared among team members.
  • Story: The business need that defines the purpose of the software to be developed for a user. Stories are usually sized so that a single iteration is sufficient for development, and they are usually written as “role can do task”, for example, “An Administrator can add a new User”.
  • Task: Definitions of all subtasks for a single story. For example, for the story “An Administrator can add a new User,” one of the tasks might be “Connect the new component to an existing security component.”
  • Backlog: A repository for stories that are targeted for release during iteration.

Role of a technical writer in Agile based projects

As part of the team working in the Agile development environment, you are expected to inform the team what is to be delivered at the end of an iteration. Working on iterations has a definite effect on the scope, content, and presentation of your deliverables. Daily status should be communicated to the team.  Some techniques and certain deliverables are well suited for documenting products that are developed in an Agile environment:

  • Using a topic-oriented approach: Topic-oriented writing is a defining aspect of information mapping and Darwin Information Typing Architecture (DITA). In information mapping, complex information is broken down into basic components, and then these “chunks” of information are structured in a user-friendly way.

    DITA is meant for creating individual topics that you can combine and reuse in different types of documentation and in different delivery formats. This makes sense in an Agile environment, in which “the right documentation, at the right time” is the main goal for all documentation - end-user and internal

  • Translating user stories to task-oriented topics: The Agile environment is linked to a very famous saying – “Don't tell me how it works, tell me how to use it”.

    Task-oriented writing is writing in terms of how the user carries out the task. Your users are interested in knowing practical information – how to – information, rather than the details on the internal structure of the software

  • Creating just-in-time documentation by applying minimalist principles: The minimalist design approach is originated by John Carroll and his colleagues at IBM. This approach has played a vital role in optimizing user support, in learning-to-use software. According to this approach, avoid wordy overviews that are not task-based. Also, do not document obvious procedures, such as how to cut and paste text or print reports.

  • Participating as an active team member: Being an active member of the Agile team is crucial to a writer’s success. The lack of internal documentation makes full participation in the team an absolute necessity. Figure 2 shows various communication methods that can be used to gather information for effective documentation.

Usability Engineering Lifecycle - HCL Tech
Figure 2**: Effectiveness of various communication modes



As programmers, the technical writers can also use Agile techniques in their writing assignments to become an integral part of delivering useful software.

* (Copyright 2006 Scott W. Ambler)

** (Copyright 2002-2005 Scott W. Ambler. Original Diagram Copyright 2002 Alistair Cockburn)

More from Harinder Sehgal

Contact Us

We will treat any information you submit with us as confidential.

We will treat any information you submit with us as confidential.

Sign in to Add this article to your Reading List