Category: Technical Documentation
Last updated on Dec 28, 2022
Is agile at odds with documentation? Not at all. But some say it is.
In the past, companies have followed an overly rigid plan for writing their documentation. This results in a ‘user manual’ that never gets read. Sometimes documentation can be ‘politically motivated’ and not produced for the benefit of users.
This type of documentation gives the field a bad name and its reputation for being ‘a waste of time’. So some say to dispense with product documentation altogether – good products document themselves. And similarly, these companies neglect their documentation.
The key to documentation success is to follow the middle road.
Done well, and done agile, product documentation has the potential to transform the efficiency of your team – and boost customer satisfaction with your product.
Implement a knowledge base system today and reduce your customer support cost by 67%Signup now
Traditionally, software development has been conducted in a monolithic way.
Every project requirement was captured upfront by an analyst, all the review processes were done, and every stakeholder approved the proposal – all before a single line of code is written.
This resulted in major failures in developing the software. The agile methodologies changed the whole process and resulted in much better outcomes and success rates.
According to Wikipedia:
“Agile software development describes an approach to software development under which requirements and solutions evolve through the collaborative effort of self-organizing cross-functional teams and their customer(s)/end users(s). It advocates adaptive planning, evolutionary development, early delivery, and continuous improvement, and it encourages rapid and flexible response to change.”
In this article, let’s take a look at 5 key strategies to adopt the same techniques that worked for software development in documentation creation.
You need both software and documentation for a successful product. Once you have your working product beloved by your users, how do you make sure you have the right documentation for them?
By following agile practices.
Next, we’ll launch right into our;
When using agile methodologies, teams can sometimes pack so much work into each cycle that they don’t leave time to document. This becomes a race to document at the last minute, resulting in poor docs and stressed writers.
This is a huge mistake. Your documentation considered as an indispensable part of your shippable product. Factor in the time needed to document, just as you would for coding.
Since documentation produced as a lasting record for your product, it may get caught up in making it perfect.
Using agile methodologies, produce just enough documentation that will get you to market as quickly as possible. Don’t aim to comprehensively document every feature or possible use case of your product.
Instead, identify the most important areas for your users, and cross-reference these with your organizational priorities. The result is your final documentation.
Discover a better way of software product documentationStart free trial
Producing documentation in a user-focused context means that your docs should be formulated in response to user need.
In order to prioritise your user’s needs, you must find out exactly who your users are! If this sounds obvious, are you pair testing your new product features (and docs) on real users?
Use the act of writing documentation as a way to catch errors that will confuse your users.
This approach is perfect for any SaaS company continually iterating its products. Each time you roll out new features, write accompanying documentation to match.
In agile software development, if you try to create all the documentation for the final product in every cycle, you’ll fail. Focus on documenting each new feature per cycle, and save polishing for just before release.
Produce some provisional documentation, always being aware you will need to revise it. As you near the end of development, your docs can become finalised.
Agile is less to do with actual processes and more of an attitude towards product development. Your product isn’t shippable until you have the accompanying documentation.
The key is to find a balance. Avoid creating all your documentation at the beginning of your development phase, or racing to complete it all at the end.
Just as business purposes can change throughout development and after launch, so does your SaaS documentation. Keep revising the end purpose of your documentation so you always feel confident you’re on target.
At the same time, travel as light as you can and produce the bare minimum documentation. What you do produce should be as simple as it can be.
Even if you’re a documentation evangelist, the aim is still to have as little documentation as you can. That means delete anything you don’t need, or you risk confusing your users.
To produce documentation in an agile manner, the benefits of your documentation should be carefully considered before embarking on production. The benefits should outweigh any cost incurred through creating and maintaining your docs.
Ask whether you NEED the documentation – not whether you want it.
Someone in your team needs to have an overview of your documentation strategy and the ability to decide what you need to produce at every step.
If you have a technical writer or other documentarians on your team (and you should), they must be fully involved in the development of your software. They can take on the role of advocate for your user, and work closely with developers and product managers to decide what documentation is necessary.
Respect the authority of your documentarians and believe them when they suggest improvements. Make your technical writer an active member of your development team trusted by your engineers and product managers.
Unlock the power of writing. Developed with love for technical writersGet started now
If your company well recognizes the users, any documentarian will be gold dust. They are your user advocate.
You must see the process of creating documentation in an agile context.
You should examine your documentation to see how it can best fit into your product development lifecycle. In the same way, you should not treat it as a box-ticking exercise.
Each company is different, and each project in each company also has its own requirements. That means documentation needs will always be unique, and one size will never fit all.
Try to avoid ranking different tasks in your business as ‘better’ or ‘worse’ than any other. It’s impossible to say that software is more important than documentation since each is completely distinct. Each is wholly necessary for your product.
Don’t expect your developers to produce your docs, though. That will be up to your technical writers.
Instead, focus on adapting to change and prioritising the needs of your users throughout development. Give every member of your team a platform to voice what they think is best for your product, and avoid doing anything just for the sake of it.
If you create a culture where the shared goal is more important than individual success, your documentation will fall into place more easily.
As with all business objectives, ask whether you really need this documentation. And then deliver it.
Every SaaS startup needs the perfect platform to host their user documentation. Try out Document360 today.
Image credit: Agile Project Management by Planbox via Wikimedia Commons