Using Agile to Write User Documentation as a Team

How to share the load of user documentation.

I recently presented a webinar about agile technical communication with TechCommNZ
(The Agile Technical Communicator). During the question and answer session, I got a lot of inquires as to how best work with other collaborators on user documentation. This inspired me to write a blog article or two about it. In this first blog article, I will discuss the differences between system and user documentation and take a look at some techniques on optimizing user documentation as a team.


Agile Manifesto core value

One of the core values of the Agile Manifesto states to have:"working software over comprehensive documentation". It argues that spending an enormous amounts of time spent on documenting the product for development and ultimate delivery. Technical specifications, technical requirements, interface design documents, test plans, documentation plans, and approvals are required for each. The list is extensive and a cause for the long delays in development.
Agile does not eliminate documentation, but it streamlines it in a form that gives the developer what is needed to do the work. Agile documents requirements as user stories, which are sufficient for a software developer to begin the task of building a new function.
Source: smartsheet.com

This is what I categorize as 'System Documentation'.

Photo by UX Indonesia on Unsplash

System documentation

As I mentioned earlier, system documentation includes such documents as risk assessments, functional and technical requirements, test scripts, as built documents, definitions of done and ready — these are all shared responsibilities of the development team.

Doing so, allows risk to be managed within the development team, and the sprint. The team captures the functional requirements through: Epics, User Stories and Tasks. Not to mention test scripts, definition of done, definition of ready and so on.

What about user documentation?

User documentation refers to documentation for a product or service aimed specifically for users. Aimed to provide them with the relevant information they need to use the product or service. It could be help files, user manual, user guide, a video how to guide, white papers, product information and so on.

Where does user documentation fit in Agile?

It is all about minimizing user documentation. The goal in Agile should be: to find the right balance between documentation and discussion. User documentation is an important part of every system, Agile or otherwise, but comprehensive documentation as such — does not ensure project success. In fact, it increases your chance of failure. This is an opportunity to be lean and think about the here and now. To do so, think about...
  • Socialize the idea that “less artifact can be better” among your team.
  • Always consider: “what’s the least amount of deliverable that we need right now?”
  • Focus on the value for the customer.

Agile documentation criteria

This criteria will help us to add value in lean documentation, and provide the essential content for the needs of the team and needs of the user.
  • Essential: Document with just good enough detail.
  • Valuable: Document only when it is actually needed.
  • Timely: Documentation should be done in a just-in-time (JIT) manner, when it is needed.
Processes with no consumers is pure waste! If no one is using the output, don’t do it. 
Photo by Annie Spratt on Unsplash

Questions to ask about user documentation

These questions can be used as a guide to help your team focus on user documentation requirements.

Who

  • Who is your customer?

What

  • What are their needs?
  • What inputs do you need to produce it?

How

  • How will they read it when they need it?
  • How do you produce it?
  • How do you deliver it to them?
  • How do you know when they're ready for it?

Documenting as a team

In my ten years of working as a technical communicator within many agile teams, I have discovered that documentation should take on a collaborative approach. It should not be written by one person to perfection, and then shared with others. Instead, it should be shared often during drafts to gain input, and to optimize the value of it to users. 
As a team writing documentation, you should just focus on ‘good enough’ documentation — no, not a shabby half baked document with little content and adequate grammar. Instead, it is about avoiding big upfront details which typically means a lot of guessing and wasted time. Good enough means document what you currently know.

The key take-aways

Value and Focus

  1. Focus on the value of your content users.
  2. Focus on Just in Time documentation. That is document what you currently know and build on it when it is time to do so.
In my next blog, I will discuss the option of getting in a documentation specialist to work with the agile team.

Until next time, keep it agile!