Many software developers believe that documentation is somehow incompatible with agile development. But that simply isn’t true.
In reality, the agile approach can be applied to the way software is documented to make it more efficient and accurate than ever.
What’s more, when documentation is done the agile way, it aligns much better with software development and results in a single frictionless process.
This article will give you some actionable tips on how to accelerate your software documentation process and organize it according to the revolutionary practice of agile software development.
Let’s start!
Apply the JIT Principle to Documentation
The just in time (JIT) principle complements agile methodology perfectly.
In production and inventory, JIT essentially means ordering an exact amount of materials for production only after an order has been received.
That way, companies can avoid creating costly material surpluses while also keeping inventory costs low, which paves the way for higher efficiency in the production process.
So, how can this principle be applied to documentation?
Quite easily, actually. In this context, the JIT principle means delaying the production of documentation as much as possible instead of stockpiling documents that won’t be useful to users in the long run.
As you know, the development process for software entails many iterations of the product and constant changes and updates.
When you factor in major and minor changes, as well as patches, the product may be completely transformed by the time you’re ready for launch.
Therefore, starting to work on the documentation only once you enter the later stages of development prevents you from being left with a pile of inaccurate, outdated, and useless information.
This should make sense right off the bat until you ask the most important question: “If we push making them that far back, will we have enough time to create all the needed documents?”
That’s a smart question to ask, and you’re totally right, JIT documentation does carry some risk.
But that might not be a bad thing.
A shorter timeframe to create the documents may motivate you to focus more on the information your users will actually find indispensable.
Writing about her experience with JIT documentation, Brianne Hillmer, a senior technical writer at Splark, summarizes it well:
As applied to documentation, just in time means that we create just enough documentation, just in time.
We’re going to talk more about creating the minimum amount of documentation for maximum effect in the next section, so let’s get straight to it.
Make It Just Barely Good Enough
Just Barely Good Enough (JBGE) is another core agile practice. The rationale behind it suggests that effort results in value, but only up to a certain point.
After that, you can keep on putting in effort, but you won’t be adding value to the thing you’re creating.
According to agile principles, this point of maximum value may happen earlier than you think - at the moment when the product is “just barely good enough.”
When transported into the realm of documentation, this concept doesn’t mean you should make weak, insufficiently informative software documents.
It means creating documentation that’s just barely enough to fully satisfy the needs of your audience and nothing more.
There’s a misconception that the agile approach to software development dispenses with documentation altogether, but this couldn’t be farther from the truth.
Jim Highsmith, one of the seventeen original signers of the Agile Manifesto, said it himself:
We embrace documentation, but not hundreds of pages of never-maintained and rarely-used tomes.
His words align perfectly with the JBGE principle, as well as with the JIT principle we talked about in the last section.
Applying JBGE to documentation frees you from writing documentation that you deem unnecessary for the successful usage of your software (the parts of the diagram that don’t intersect in our Venn diagram above) and enables you to keep your documentation light.
Why is that important? That’s easy. With lighter documentation, you have a much easier task maintaining your knowledge base because there are fewer articles you need to keep track of.
And as any technical writer will tell you, documentation maintenance is the most difficult part of the document development life cycle.
So how do you know which documentation deserves to be created and which can be left aside?
That’s a more difficult question.
Ultimately, as the product owner, you’re the one who knows which parts of your software are the most interesting, or conversely, the most problematic, or unintuitive for your users—who therefore need you to provide more support.
It’s a good idea to develop your own decision-making process, but here’s a workflow that may help you in your effort.
It was designed by Scott Ambler, author of multiple books on agile methodology.
The key takeaway here is that making documentation just barely good enough doesn’t just reduce your workload when the time comes to create documentation.
It also prevents your documentation from becoming redundant, outdated, or inaccurate because there’s so much less of it to constantly maintain and verify.
Document Continuously
Now, all this talk about giving software documentation a late start and taking a minimalist approach to it may cause you to think that creating documentation is a short, one-time event.
Not so.
Once you decide to start documenting your software, it’s important to stick with it and write, update, and remove documents continuously.
That doesn’t sound very agile, does it? Well, it’s actually quite in line with the part of the agile philosophy that states you should make every iteration of the product instantly shippable.
In other words, once your software matures enough and you start documenting it, assuming you document continuously, you’ll always have a valid knowledge base to go along with your product, no matter the stage of (later) development.
Here’s what that might look like on a timeline:
As you can see, instead of putting in a giant effort to plan and design your documentation (the traditional way), you’re starting at a later stage and boosting your effort as the product becomes more complex.
The key to efficient continuous documentation is to wait for the information to stabilize.
Each iteration will have a point where the big decisions have been made and the product is stable enough to write about.
Once that happens, the documenting phase can start and there are two key principles to follow:
- When you have a longer iteration on your hands (four weeks), document as it unfolds, because the information is already likely to stabilize while the iteration is still ongoing.
- With shorter iterations (two weeks), wait to write after the iteration because the information will be stable only after the iteration is complete.
Writing continuously is a good practice because it reduces the risk that you’ll simply run out of time to deliver the documentation if you start documenting later in the project.
Also, as you’re not writing large amounts of documentation all at once, errors and inaccuracies are far less likely to happen.
Avoid Having Overlapping Docs
Another way to make your software documentation lightweight and easier to maintain is to avoid overlapping documentation and duplicate information.
The reasons go far beyond the ease of document management.
With overlapping documentation, there’s an enormous risk that the overlapping documents will contain conflicting information.
When that happens, users can experience unsolvable problems that will bring their work to a screeching halt.
Moreover, documentation managers that find the same contradictions won’t be able to tell which version is actually true.
Here’s an example of such an issue from Stack Overflow in which a user finds one clear and logical piece of information:
However, a second document brings this information into question:
There are multiple reasons why an issue like this could happen.
For instance, one document might have been updated with an older version remaining in another document, or two people may have worked on the documentation and created articles with conflicting information.
Whatever the reason, the underlying cause of the problem is that an overlapping document existed in the first place.
If this information was contained in just one document, it would have been impossible for the inconsistency to occur.
Therefore, if you want to create agile documentation and prevent all of this trouble, all you have to do is avoid overlapping documentation.
The easiest approach would be to do your best to merge smaller documents containing information overlaps into larger ones.
That way, you’ll have comprehensive documents that deal with a singular topic and minimal overlap.
Spotify’s developer documentation does this pretty well.
As you can see, the knowledge base is divided into seven topics according to platform.
By selecting a topic, the user is transported to a single document where they can find all the information they need on that topic in one place.
Here’s a document for the Web Playback SDK:
On the left-hand side, there’s a handy table of contents and you can see that all the resources are there: from authentication and installation to the source code.
As you can see, there are a lot of problems that can stem from overlapping docs. Thankfully, the solution is simple.
Just put all of the information related to one topic in one document and you should be all set.
And speaking of putting everything in one place, this piece of advice can also be applied to your entire knowledge base. That’s the topic of our next section.
Keep Your Docs in One Place
A single, efficient platform for all of your software documentation is a great way to make information accessible and always available to your team as well as end users.
And since such platforms put all of your documents in one place online and make them easy to update and edit, they’re the perfect tools for agile teams working on dynamic software projects.
Here’s Slack’s developer documentation website. It’s a great example of how everything a user or developer would need can be efficiently organized and kept in one place.
Each functionality and feature of the software is presented in detail and easy to find thanks to an intuitive interface and plenty of navigational tools, such as a search bar and a table of contents.
Users who approach the documentation have ample learning resources, such as knowledge articles and step-by-step tutorials to guide them through working with the app.
There are also support resources and troubleshooting articles to help out users who get stuck.
Most important of all, Slack’s documentation is interactive and uses text, multimedia and live code to explain, describe, and teach.
Slack’s documentation is definitely impressive, but the truth is that these days building interactive online documentation bases isn’t as difficult as it may seem.
Not if you have the right tools, that is.
If you’re using modern documentation software, such as Archbee, you have everything you need to create, update and publish comprehensive software documentation online, where it can be quickly accessed by anyone who needs it to achieve success with your software.
This kind of software is indispensable for an agile approach to software documentation because it enables you to create Wikipedia-like knowledge bases where every article can easily be updated to reflect the fast-changing nature of software development.
Since articles can be written using text, multimedia, and code as quickly and easily as creating a Word doc, as well as uploaded with a click of a mouse, software documentation can be created later in the development process, with much less planning involved.
Documentation software also comes with collaboration capabilities, making it easier than ever to involve the entire team in documentation production.
For example, with Archbee, you can chat on docs, tag stakeholders, and request SME reviews, all within a document you’re currently working on.
Long story short, if you want to document according to the principles of agile, quality documentation software that’s adapted to the needs of software development is the one tool you can’t do without.
Have Everyone Contribute to Documentation
Speaking of collaboration, quality software documentation is never created by just one person, regardless if that person is a developer or a technical writer.
Quite to the contrary, documentation should always be a team effort, and that goes double for agile environments.
Don’t forget, one of the founding principles of agile development is frequent communication and close collaboration:
The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.
In practice, this means that the person tasked with documenting the software should work closely with the subject matter experts (SMEs) working on the project.
After all, these are the experts who designed the software in the first place, so they’re the most reliable sources of knowledge and instruction when the time comes to explain how the product works.
Your interactions with the SMEs can be organized according to the needs of the project, but a good rule of thumb is to be involved from the very beginning, even if the documentation phase comes later in the project.
Another good practice to follow is to communicate often and leave no question unanswered, at least if we’re to trust technical writing experts:
Finally, keep in mind that in an agile environment, the interaction between document creators and SMEs doesn’t always have to be direct.
Agile development, when done properly, includes scrum meetings where information is exchanged and questions are answered, so it’s a good idea to reserve a seat for the technical writer in every meeting.
Carrie Miller, an experienced technical writer, makes a great point here. There’s no reason why the technical writer shouldn’t be involved with the project from the start.
The more they can immerse themself into the project from the start, the easier it will be to write the documentation once the product is solidified enough to document.
Her initial questions are also a good starting point for thinking about how to approach documentation.
They should help you build a holistic picture of the product before you dive into the specific docs that will make up your knowledge base.
Remember, good documentation is only created in collaboration.
Document creators should be involved in the project from start to finish and have an open line of communication to the SMEs developing the software.
Agile development is fundamentally collaborative and there’s no reason why agile documentation should be any different.
Conclusion
The purpose of this article was to show you that software documentation doesn’t have to be a clunky process that results in a mountain of documentation no one will ever read.
By applying the principles of agile, the documentation you’re creating will be lighter, more manageable, and less time consuming, while still satisfying the needs of its users.
The Agile approach has been around for a while now. Its principles have helped countless developers build better software. Why not find out what it can do for your documentation?
