After many years of working in software testing, I think it’s safe to say that almost no one enjoys writing documentation. Even people who enjoy writing (like me) can find it a chore, compared to other, more interesting, activities such as creating test plans or writing test automation. But documentation is extremely important! In this post, I’ll outline five reasons why, and I’ll also share five strategies for ensuring your team or company has good documentation.
Reason One: It is helpful to YOU
Think of documentation as a letter from your past self to your present self. Often in software testing we’re required to set up complex application configurations. Do you remember the details of every single setup? I know I don’t! Whenever I need to set up something complicated, I take notes about what I did. I keep those notes organized so they are easy to find the next time I need to configure something. When I find my documentation I need for something I have forgotten, I usually say “Thanks, Past Me!” out loud.
Reason Two: It is helpful for your team
When you have been working on a team for a while, you often internalize details that might not be obvious to new team members, and those details are probably not written down anywhere. Something as simple as the login information for your test users will remain unknown to other team members if it’s not written down. Would you like to stop what you are doing several times a sprint to give your teammates login information when they need it, OR would you prefer documenting this information and placing it in a location that is easy for your teammates to find and bookmark? I know which I’d prefer!
Reason Three: It is helpful for people outside of your team
Your team probably has specialized knowledge about how your feature or product works that people outside your team don’t possess. The more you can document how to set up your feature, how to configure users for the feature, how to test the feature, answers to common questions, and how to troubleshoot the feature, the less you will have to stop what you are doing to help others with their feature problems.
Reason Four: It helps prevent missed requirements
I was once tasked with testing a rewrite of a very important feature. The feature was very complicated and had dozens of configuration settings, resulting in hundreds of testing combinations. None of the features were documented, leaving me to guess, experiment, and ask the product manager questions to get the information I needed. Shortly before the rewrite release, the product manager discovered that we hadn’t coded one very important configuration setting. We didn’t code it because we didn’t know about it! Having written documentation about every single configuration option would have prevented this problem. (And yes, I was documenting everything I learned, so the next group of people to test the feature would have the information they needed!)
Reason Five: It helps prevent missed test cases
Think about the most complicated product you have ever tested. When you think about all the different ways it can be tested, do you remember them all? Are you sure? Documenting how a product works and all the different settings and user journeys is extremely helpful when determining what should be regression tested. With proper documentation, you will be much less likely to forget about testing a feature. And yes, documenting your regression test plan for reuse is a great idea as well!
Now that we’ve examined the five reasons documentation is so important, let’s look at some helpful documentation strategies:
Strategy One: Know that not everyone is good at documentation
Because most people don’t enjoy writing documentation, many teams who want to add documentation decide that everyone on the team should take turns writing it. Unfortunately, this will result in some poor documentation from the people who aren’t good at it. Not everyone is good at taking a complex topic, breaking it down into smaller parts, and describing those parts in a clear, organized fashion. If you make everybody write documentation, expect to spend a lot of time fixing the poorly written items.
Strategy Two: The people who are good at documentation usually hate it less than the people who aren’t good at documentation
There are people in the world who actually enjoy figuring out the clearest way to explain things. Some of those people are technical writers, and if you have access to them, consider yourself lucky! Most teams will need to settle for finding the developers, testers, or product managers on their team who are the best explainers, and asking them to create the documentation.
Strategy Three: Make sure the documentation doesn’t fall to just one person
If you choose just one person to write the documentation for your team, chances are they will wind up resenting it, because they will need to take so much time away from their coding and testing to do it. That’s not fair to them. Choose at least two people to share the load.
Strategy Four: Build in times for documentation
For testers, It’s already hard to balance activities like creating test plans, executing test plans, writing test automation, and fixing flaky tests. Developers have to deal with meeting product deadlines, conducting code reviews, and fixing tech debt. Rather than expecting people to prioritize documentation on their own, a really useful strategy is to build in the time to do it. This can be done in a few different ways: documentation tasks could be added to the sprint board and estimated, so the time is included along with the other tasks; a team could choose one day a month to focus on documentation; or a team could set aside one sprint every quarter to focus solely on documentation. This reduces the anxiety that testers and developers feel when they are trying to balance too many priorities.
Strategy Five: Know that maintaining documentation is much easier than starting documentation
When you first start documenting your team’s information, it can feel like it will take forever to get it done, and you may imagine that it will always be that way. But once the documentation is written, it will take much less time to maintain. The team will simply need to remember to update the documentation whenever something changes. Building in a regular time to review the documentation will help keep the documentation at the front of everyone’s mind. Additionally, your documentation will help your teammates and others find the information they need on their own, reducing interruptions and context switching. Some of that saved time can be used to maintain the documentation.
With strategic planning and focus, teams can create useful documentation that will serve themselves and others in the company, helping them release quality products on time.