I've been thinking about documentation in Agile for a long time, but only recently have I thought about what Agile documentation development itself might look like. Organizations have adopted Agile for its ability to empower teams to create high-quality products faster. From that angle, I wondered whether a documentation team might see some gains by adopting "docs Agile."
To clarify, I'm not talking about including technical writers on Agile teams (although I have written about it in the past). Instead, I'm doing a thought experiment to see what the Agile Manifesto would look like if, instead of being applied to development teams, it applied to documentation teams. I’ve tried to keep the docs team incorporated with development and testing during my thought experiment. Overall, I think these ideas are instructive in terms of what writing teams can do within an Agile framework.
Because I have a lot of thoughts on this topic, I’ve broken it up into two parts to make it easier to read. You can read Part 1 here, or you can download a copy of the full article as a PDF.
Agile Manifesto Refresher
As a refresher, here are the 12 Principles of Agile Development:
Our highest priority is to satisfy the customer through early and continuous delivery of valuable software.
Welcome changing requirements, even late in development. Agile processes harness change for the customer's competitive advantage.
Deliver working software frequently, from a couple of weeks to a couple of months, with a preference to the shorter timescale.
Business people and developers must work together daily throughout the project.
Build projects around motivated individuals. Give them the environment and support they need, and trust them to get the job done.
The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.
Working software is the primary measure of progress.
Agile processes promote sustainable development. The sponsors, developers, and users should be able to maintain a constant pace indefinitely.
Continuous attention to technical excellence and good design enhances agility.
Simplicity – the art of maximizing the amount of work not done – is essential.
The best architectures, requirements, and designs emerge from self-organizing teams.
At regular intervals, the team reflects on how to become more effective, then tunes and adjusts its behavior accordingly.
So what would these mean if translated to a docs team?
#7: Working documentation is the primary measure of progress.
What do we mean by "working documentation"? It's difficult to apply a parallel to software. After all, working software is software that works: it functions and doesn't have bugs. Does that mean "working documentation" doesn’t have any "bugs" like grammatical or description errors?
That doesn't feel right. Nor should it. After all, it's hard to say documentation is "working" if it's simply error-free. For documentation, the definition of "working" is "serving the needs of the user." To serve the user, the docs need to be accessible – technologically, physically, and verbally. This goes for every member of the audience at which it’s directed.
Is it in a format they can access?
Is it stored in a place they can reach it?
Is the language clear and understandable?
It also needs to educate the user – not just how to perform an action but why, the context. This is particularly important in enterprise software, where you often have entry-level users performing small parts of a large and complex process.
Finally, the docs need to be architected in a way that makes it easy for users to find what they need. Does context-sensitive help make sense? What about search capability or navigational aids? How do your users want to interact with their docs and how can you make it easy for them to navigate?
Turning this principle toward documentation has a unique effect: the meaning of the documentation principle informs the meaning of the software principle. Using our documentation principle, we see that "working" software isn't simply bug-free software, but software that best serves the needs of the users. If your software is a labyrinth of screens and fields that don’t coherently hang together, or in which processes don't fit together clearly, I'd argue it isn't "working" whether it has bugs or not. Interestingly, a good indication of whether your software works from this perspective is how easy or difficult is it for the writer to document the processes and procedures associated with it. If the writer has a difficult time describing some aspect of the software, dive into that with them to find way to improve the system to work better for your users.
#8: Agile processes promote sustainable development. The sponsors, developers, [writers,] and users should be able to maintain a constant pace indefinitely.
This principle ties in nicely with my previous point: if your software is "working" in terms of serving the users and fitting into previous work, it should be possible to maintain your development pace indefinitely. This is also the case for the writer: the writer should be able to keep up with development without falling behind.
The keyword in this principle is "sustainability." From a documentation perspective, sustainability is about creating scalable templates, style decisions, documentation delivery systems, and information architecture.
Naturally, this is no small task. To set up scalable assets, the writer needs to know where the project is going and how it's expected to grow during its lifetime. This is where Principle 4 becomes incredibly important: access to the business can make or break the writer's ability to set up their documentation and processes in a way that promotes sustainable writing.
#9: Continuous attention to technical excellence and good design enhances agility.
Like the principle above, the writer must constantly monitor their design – including information architecture and documentation delivery systems – to enhance their own agility and ability to keep pace with development.
Under this principle, the documentation team takes the time to develop well-designed documentation systems, especially in terms of architecture and delivery.
#10: Simplicity—the art of maximizing the amount of work not done—is essential.
This might be my favorite principle. Similar to Principles 2 and 5, I have some experience with rework and have discovered myriad strategies to avoid (and cope) with it.
Some of this principle can be achieved through tool usage. For example, I use MadCap Flare at work, which provides several options to help avoid rework and improve the simplicity of the project. One is a tool that allows the writer to create a “snippet” of text that can be linked to from any topic. The writer enters the necessary information once and adds a link when they need to reuse that snippet. Since there's a single source of truth for that text, the writer can quickly and easily update all instances by updating the snippet.
Another Flare feature that helps reduce rework is conditional tagging. This lets the writer dynamically tag their content for different purposes, then generate documents based on mixing and matching those tags. Like snippets, this allows the writer to write a piece of content once and reuse it for multiple purposes, as well as to update that text once rather than across multiple Word documents. Features like this in Flare – and in other good-quality help authoring tools – can make generating tens or hundreds of documents significantly simpler.
In addition to using tools appropriate to the mission of simplicity, writers should also use this principle to find novel solutions to the problem of rework. They should also be encouraged toward a "just enough" approach to documenting the software. This isn't to say the docs should be paltry or deficient; instead, the documentation should provide exactly what the user needs and no more. This can be a difficult mark to hit across audience groups and certainly when a project is young, so it's important for writers to solicit and receive feedback from the users themselves. Over time, as the writers get a sense for what their audience already understands and is familiar with, they will achieve a level of simplicity in the docs.
#11: The best architectures, requirements, and designs emerge from self-organizing teams.
I think this principle applies to documentation teams in two different ways: in regards to the development team as a whole, and in regards to the documentation team itself.
As far as the development team is concerned, the writer is free to join a new team under this principle. If we assume any software product has one or more user base, the need for documentation is obvious. From within the team, the writer can establish what documentation is required and what level of effort it will require to create and maintain it. The writer also uses their position within the team to inform development about users concerns they see through their work, helping the team dynamically improve the software.
As far as the documentation team is concerned, the writer is free to organize with other writers to achieve documentation tasks. This includes flexibly helping on other projects as documentation needs fluctuate, as well as providing a sold backbone of writing support for docs QA, editing, style guide creation and maintenance, and other documentation tasks. These smaller "teams within the team" can also develop novel solutions to common documentation problems as well as provide support and solutions for project-specific documentation challenges.
#12: At regular intervals, the team reflects on how to become more effective, then tunes and adjusts its behavior accordingly.
Similar to Principle 11, this principle applies to both a writer’s interaction with the development team as well as their interaction on the documentation team.
Under this principle, the writer attends retrospective meetings with the development team, provides and receives feedback on the sprint, and suggests solutions to overcome challenges. Like any other team member, the writer must be open to feedback and work collaboratively with the team to achieve workable solutions to common problems.
As regards the documentation team, they should also meet regularly to discuss issues unique to their team: style guide issues, tasking documentation work on stories, editing processes, and so on. By working to continuously improve the documentation not only at the project-level but at the organizational level, all projects will rise together in documentation quality and delivery.
Want to mull this article over offline? Check out my eBook, “The 12 Principles of Agile Documentation.”
