A PWC study has shown that Agile products are 28% more successful than traditional ones.
Sounds great for software and product development, but what about writing the accompanying documentation?
Well, many companies have successfully applied Agile principles to writing technical documentation, and we’ll show you how you can do that, too.
You probably won’t have to transform your document creation process drastically; if anything, you’ll simplify it.
That’s right, Agile encourages teams to document when necessary and no more than necessary.
Such an approach to documentation will save your team time and money and still provide your users with equally effective resources.
Now, let’s explore the details of the methodology, starting with the core values and principles.
Agile Approach to Documentation Explained
Writing just enough documents, just in time—that’s the Agile approach to documentation in a nutshell.
Whether you’re new to software engineering or a seasoned professional, you’ve probably encountered the term “Agile” applied to everything from development to testing.
The popularity of the approach has been steadily increasing over the years, and based on Google Trends data, it’s still on the rise.
Since the trend is here to stay, it’s vital to understand what Agile is and how you can apply it to creating technical documentation.
The Agile methodology boils down to organizing software development into shorter, iterative cycles of work.
Its core principles are described in the Agile Manifesto, a document designed in 2001 by seventeen software development experts.
However, when you start reading the Manifesto, you’ll notice a potential issue regarding applying the Agile principles to writing technical documentation.
However, before we take the guideline that prioritizes software over comprehensive documentation at face value, we should remind ourselves that both items play a role in the final software product.
The Manifesto doesn’t advise against writing technical documentation.
Instead, it merely points out that the process of creating documentation shouldn’t overshadow the project’s actual purpose, which is presenting clients and users with an effective product.
In other words, the phrase just enough documents, just in time means it’s better to document the ongoing operations and avoid writing potentially redundant documentation for the planned features you may end up not implementing.
When it comes to timing document creation following the Agile approach, the essential piece of advice is to work on technical documentation as the product develops, or at least to note down the foundations your technical writer can later build on.
This practice is also in line with another Agile core value: responding to change over following a plan.
Embracing the fact that the development plans often change will help you write relevant and accurate documents when there’s a real need for them, instead of sticking to potentially outdated plans you’ve set at the beginning of the project.
Hopefully, Agile documentation sounds less intimidating now.
You shouldn’t let the seemingly complicated methodology deter you from practicing such an effective approach to writing technical documentation. Here are some best practices for creating technical documentation.
So, let’s see what and how you can document by applying the Agile mindset.
What, Where, and When of Agile Documentation
As we’ve seen, it’s perfectly fine not to document everything in Agile. Still, it’s easier to implement the methodology when you have direct pointers to follow.
Because of that, we’ll start with listing exactly what you should and shouldn’t document.
There’s a widely spread misconception that Agile equals no documentation. The myth is not only incorrect, but it can also make your project manager cry, so make sure you don’t fall for it.
In reality, it all depends on the specific project you’re working on.
As we wrote in our article about software documentation types, not each software project requires release notes and reports.
Release notes may be a standard part of process documentation, but according to the Agile methodology, that isn’t enough of a reason to commit to a piece of documentation that doesn’t add value to your product.
Instead, you should decide on specific documents you’ll need before, during, and after the project has been rolled out.
So, ditch the market requirements documentation if creating a user guide would enhance the product more.
When it comes to the question of where to create documentation, the guiding principle is to decide on one repository and do all the updates there.
After all, you don’t want pieces of information scattered around Jira, Trello, and Google Docs, which is often the case in teams of multiple members.
Choosing one place to build your documentation prevents vital information from getting lost.
Additionally, it enables the entire team to access the documents anytime throughout the development process, which is truly in agreement with Agile practices.
If you’re looking for a single platform where you can document your development process, write technical documentation, and even share it with end-users, Archbee may be the solution for you.
Archbee, our product documentation platform, uses a system of mentions, tags, and links to facilitate collaboration.
Similarly to what the Agile Manifesto describes, using Archbee will help you place “individuals and interactions over processes and tools.”
So, if you’re looking for your where of Agile, Archbee is a document repository worth considering.
Lastly, when it comes to the question of when to write technical documentation, the Agile method emphasizes the just-in-time (JIT) approach.
With JIT, you create documentation in parallel with product development. In other words, the team writes living documents.
That way, you can streamline the efficiency of the process because your technical writer doesn’t have to scrutinize technical documents for the information that has become obsolete after the release of a newer version—all info is always up to date.
Reading Just in Time (JIT) Documents
Besides playing a role in the document creation aspect, the JIT approach to documentation can also be applied to how users read the documents. Let’s find out how.
In the Agile-inspired software development process, the term just-in-time refers to writing documentation synchronously with development, not earlier or later.
Such an approach allows the team to focus their energy on pressing matters and deal with relevant issues, ensuring that no unnecessary documentation is written.
However, end-users also want to use their time effectively. This is why bulky user guides are slowly getting replaced with better, navigable knowledge base formats.
In the image above, you can see user documentation created by TalkChief, a business phone system.
As you can see, the product wiki doesn’t only show an overview of the entire solution.
It also lets users zero in on only those issues and questions they’re interested in, when they need them, in line with the JIT principle.
Structuring your tech documentation in a way that lets end-users find information more quickly saves their time and lowers the learning curve of your product.
So, when writing documentation, don’t forget that your in-house team isn’t the only side interested in accomplishing the task swiftly, and make sure the end-users can also access the relevant information just in time.
Agile Documentation Best Practices
If writing technical documentation effectively sounds like something you’d like to try out, you’re probably interested in how exactly you can apply the Agile approach to writing.
To help you out, we’ll review the two best practices we find crucial for establishing a successful Agile workflow in technical writing.
Let’s start with the people in charge of the documents.
The Agile methodology places a lot of emphasis on team collaboration. And indeed, teamwork will ensure that the documents contain accurate, straight-from-the-source information.
However, things can get a bit chaotic when engineers, designers, and support specialists all contribute to documents. That’s why a technical writer is an excellent addition to the team.
A convenient way to find technical writers is to post your advertisement and allow sharing on designated platforms, such as Writers Write.
You may notice some familiar companies looking for tech writers there, too.
Hiring platforms let you represent your business and describe the role clearly, increasing the chance that only the candidates with relevant technical skills apply.
Once you narrow down your candidate pool based on their applications, don’t forget to ask the appropriate interview questions to secure the most fitting technical writer for your team.
The writer will organize and unify all the JIT pieces of information into one comprehensive unit.
Still, you shouldn’t count on the tech writer to iron out the inconsistencies that may arise—it’s better to prevent them altogether.
This is why our second tip is to keep the documents as simple as possible.
Take a look at Spotify’s troubleshooting pages to see an example of simple yet effective user documentation.
The page introduces a frequently asked question and provides a straightforward answer, with no unnecessary details.
If a user needs more information, they can click the links and find the relevant info on their own.
Spotify walks users through the solution in the simplest way possible.
Arguably, the help center could look better if the answers were supplemented with screenshots, but you shouldn’t forget that Agile aims for simplicity.
Essentially, the more complex documentation you create, the more difficult it will be to maintain later on.
Therefore, keeping the documents light and uncomplicated will help you create them faster and simplify the maintenance process as your product evolves.
JIT Documentation Case Study
Although Agile and JIT documentation may take some time to get used to, they still yield tangible results.
We’ll now analyze how Brianne Hillmer, a senior technical writer, used the JIT approach to writing docs and increased the success of SurveyGizmo’s user documentation.
In 2014, Hillmer became the sole person in charge of SurveyGizmo’s documentation.
She soon realized that the content was full of instructions that had been written before the features were even released, abounding in incorrect terminology.
That’s why Hillmer turned to JIT documentation and started writing instructions for the actions that the actual users wanted to accomplish and couldn’t figure out on their own.
As a result of the JIT documents, pageviews per session dropped.
And as Hillmer says, “Only in documentation is fewer page views a good thing”—because that means that users can find solutions easily.
Since your aim should be to resolve your users’ issues in as few steps as possible, you should provide users with JIT documents they can browse as needed, rather than making them comb through convoluted product descriptions.
Here’s a screenshot of one satisfied customer who even went to thank Hillmer for a helpful article.
You can, too, receive such positive feedback on your documents with some effort.
However, it’s worth noting that Hillmer extended the meaning of just-in-time.
Her success in switching to JIT was so significant because she also kept updating the documents based on the customer feedback that the company received after publishing the docs.
As we said, the Agile approach advocates creating documents as needed.
Well, in this case, some changes were needed after the customers had shown that they couldn’t fix certain issues using the existing instructions.
So, if you want to create effective Agile documents, don’t forget to occasionally check in with the actual users and respond to their feedback.
Conclusion
With so much ado about the topic, it’s not surprising that people sometimes consider Agile to be something abstract and convoluted.
However, it’s quite the opposite — the Agile Approach to writing technical documentation & just-in-time docs calls for simplicity in all stages of product development, including technical writing.
So, if you ever find yourself falling into the trap of overcomplicating documents, you might want to try out the Agile approach and eliminate the unnecessary steps and information.
