We’re not the only ones who believe in this, have a look…

Translating User Stories into Task-Oriented Topics

In an Agile environment, development is driven by user stories, which define the tasks that end-users want to accomplish with the software. User stories must be customer-focused, succinct, and testable, and writers can leverage them to create user-focused, task-oriented documentation. Task-oriented writing not only complements development’s use of user stories, but it is an absolute necessity given short iteration cycles and an often limited number of writing resources. The requirement to create installation and configuration information and solid procedural information (probably in an online Help system) often leaves very little time in any release cycle to create much conceptual or best practices information. Such information can, however, be produced following a particular release cycle. The focus on tasks within a cycle, however, helps writers achieve minimalism, another technique particularly well-suited to documenting in an Agile environment.

Just-In-Time Documentation Also Means Just Enough

Minimalism in technical documentation has been advocated since IBM’s John Carroll wrote The Nurnberg Funnel: Designing Minimalist Instruction for Practical Computer Skill in 1990. Minimalist principles are especially relevant when you adapt Agile methods to produce working documentation that complements working software at the end of short iterations. For example, you should avoid wordy overviews that are not task-based, and you should not even document obvious procedures such as how to cut and paste text or print reports.


So how can agile methods help?

  • even agile methods include specs
  • a product owner knows where he is going
  • if properly adhered to:
    • agile methods use story creation
    • agile methods use test cases

A lot of these can be transposed at least to documentation candidates. These stories can also allow a product owner or manager to decide if documentation is necessary.

The question is how? You have to have a strategy and the proper tools.

First the strategy. You need an editorial strategy – this is the specs of the documentation part of the software project. It defines the ambitions, scope and depth of what should be produced. It also involves concepts like:

  • ask yourself if what is written is needed – better, ask support or a known user. Make sure you understand the user needs.
  • only write scope that can be maintained – too much is just too much.
  • document essentials first – they’re not what you think, for instance, documenting a main window as such probably does not add any value.
  • just barely good enough (JBGE) – this is the first level of ambition. Anything else will be suggested by a review cycle, user comments or other forms of feedback.
  • get it done in time – with the end of a sprint or at worse a release.
  • check what YAGNI means, and keep it in mind (you aren’t going to need it).
  • remember IBTN – it’s better than nothing.

Get the developers involved. Yes. They have a role even in documentation. They did the stuff, so they know a bit about it. It may not be the best pitch or writing skills but it is better than nothing and can be worked on.

Remember in-situ. Design the documentation from the ground up (see Writing software documentation from the ground up). Put yourself in the place of the user. Take context into account (see What we mean by contextual documentation).

A step up from the ground; When the user has read the basic, what else does he actually need? These are connex subjects which we divide in how-to topic (procedures), explanations of concepts, and faqs, information formulated as questions he will ask (not you).

Find the tools. One tool we are seeing more and more is defining persona for analysing user experience. This is dealt with in Personas as a means for mapping user experience for information delivery. To summarise, we would try to come up with the following table after defining personsa for beginners, literate users, proficient users and experts.

Beginners Literate users Proficient users Expert users
  • They need to get started and comfortable fast.
  • Satisfaction is a priority.
  • They need to get the basic job done.
  • They have to learn specific concepts.
  • They will have questions.
  • They need quick recipes.
  • They need to find out how they can improve their processes.
  • They don’t need beginner stuff.
  • They need to identify what changes in the software rapidly.
  • They may not need help.
  • They can contribute.
  • Provide short learning steps as howtos.
  • Explain basic concepts.
  • Suggest with in-built help.
  • Get them to evaluate and improve on their feedback.
  • Concentrate on tasks.
  • Provide a greater span of concepts.
  • Design faqs with support and continue building them with support.
  • Concentrate of their goals. If you don’t know them, then talk to them.
  • Find a way to hide what they don’t want.
  • Map out changes in versions
  • Gettheir opinion.
  • Encourage contribution and feedback.

This is an example and not a method. It is aimed at helping us see how we can keep it simple.

What would be ideal is having stories written using the same persona.

When can user documentation be started?

Early. See When can user documentation be started?

Who can write

If you have technical writers, train them as agile information strategy technicians or managers. If you don’t then you might want them involved as freelancers just to fine-tune and brush up.

Anyone in the project can contribute.

Support teams have particularly useful input. If they contribute then they’ll find content already prepared for their own use later.

Testing, testing, review and validation

This should be done in the same rhythm as the software. A dashboard helps to manage feedback from testing.


Feedback is essential, not only to keep the documentation up to date but also to test its pertinence and measure user satisfaction.