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.
This is what I categorize as ‘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?
- 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.
Questions to ask about user documentation
These questions can be used as a guide to help your team focus on user documentation requirements.
- Who is your customer?
- What are their needs?
- What inputs do you need to produce it?
- 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
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-away
Value and Focus
- Focus on the value of your content users.
- Focus on Just in Time documentation. That is document what you currently know and build on it when it is time to do so.
Originally published at https://www.lukepivac.com on May 20, 2020.