Do you constantly postpone the Documentation on your projects? Well, maybe you have to read this blog post! It was written from the QA approach, but sure you will find something that helps you to organize all the information on your mind.
What is Software Documentation?
Why do we find documentation so unattractive? Is documentation boring? Is it just fun for the QA team to break things and find bugs? The truth is that documentation can be tedious, but it is one of the best practices within a project.
By definition, ‘documentation’ is a set of documents — usually official — with which we prove or recognize something. In software development, and from the QA approach, it becomes a guide to understanding what is necessary to perform a task.
Documentation becomes a guide to understanding what is necessary to perform a task.
Why should you care?
In simple terms, documentation helps us do what we need to do. Saying it in other words: it helps us to get things done. In the same way, it helps users and teams to spend less mental energy; to create consistency in the information, processes, and plans; and to minimize workload.
Your memory can’t be trusted
Having information in our memory, without any kind of backup, can be a lot of responsibility for a single person: Is this the admin user’s password? Had I performed this test before? Was this document related to another? When something happened some time ago, our brain begins to make its own version of the events. This means that we are likely to forget details.
Documenting helps us organize our ideas, visualize a point to start acting, make a test plan to follow, keep track of our data bank, and compare the results of previous cycles. The objective of doing it is to define strategies, prioritize tasks, reduce effort, and increase the efficiency of your day.
Documentation helps us to get things done.
In a situation in which only a few people know certain details of the project and there is no documentation on them, the probability of loss of information is greater. Then, it becomes a risk for the project and it may even result in customer dissatisfaction.
So, as a piece of advice: don’t trust your memory! Taking notes is way better!
Good communication: always the key
Surely, documentation will make things transparent to your team, letting them know what you’ve been working on. As a fact, it is known that soft skills are vital to the success of a project; for example: communicating with your coworkers, either in person or remotely, becomes an everyday thing. That is to say that documentation (in some ways) helps us practice and improve the way we organize and express our ideas.
QA usually interacts with different roles and levels in a company. We are always searching for bugs and errors in the user experience. For this reason, to transmit this information it is super necessary to have or develop good communication skills: QAs must be experts in communicating their ideas!
QAs must be experts in communicating their ideas!
Who’s going to read my documentation?
To be honest, all the documentation that you do will be mainly beneficial only to you. Also, while performing this process, you will learn to be more orderly with your tests, the data bank you use, and the results obtained. As well, that will allow you to have better control over the processes in QA.
Indeed, there are situations where documentation will play a very important role. For example, if a QA member takes vacations or leaves the project, the documentation will allow the rest of the team to know what they have been working on. Based on that, they will be able to perform the tasks that come up until the QA returns or a replacement is found.
Leaving a project and coming back after a while can be another situation. It will be necessary to refresh your memory by taking a look at the documentation that you made in due time, it is at this time when you thank your “past self” for having made such good documentation or regretting you for not having documented.
Good documentation will allow you that in the learning curve you acquire more knowledge in less time.
If a new person joins the team, they will need an “onboarding” in which they will be explained how the project works; including important details such as the flow of processes, roles that a user can have, project progress, tests carried out so far, and everything they need to know in order to start their activities. A good document will allow you that in the learning curve you acquire more knowledge in less time.
Any tips and good practices?
- It describes processes in an orderly and chronological manner, in such a way that it allows you to follow the right steps to perform a task.
- Do not hesitate to use visual tools such as flow diagrams and concept maps if a process seems complicated to explain.
- Keep all related documents grouped together. That way, it will be easier to know which documents are related to each other.
- Grouping parameters and resources like tables, diagrams, email accounts, passwords, etc. will allow you to more easily locate what you need.
- Use specific nomenclature for everything you need, such as emails, passwords, file names, etc. (Example:
user+manager+01@mail.com) - Give descriptive names to your files or you’ll forget what they were about.
- Keep order in the version of your documents using numbers or dates. (Example:
table_comparativ_01). - Note how the changes will be identified between the newer and older versions.
- Do not make corrections overwriting data and do not correct data written by another person if you share the editing of a file with a collaborator.
- Make sure the level of detail in your writing is high and answer the questions: what, who, how, why, and when.
- It is good practice to create a new version of the documents at the end of the development process based on the documentation created at the beginning.
- Document only when it is necessary, avoiding falling into excessive documentation that will not be useful.
- Use tools to track requirements, bugs, tickets, tests, and results. A tracking tool is more effective than writing a document in plain text.
- Use templates. The header, footer, titles, font sizes must be consistent in documents. It is also good practice to have a front page, a contents table, a table of images, and a glossary.
To sum up
While no one will require you to take note of every tiny detail, you will begin to develop criteria to detect what needs to be documented
While no one will require you to take note of every tiny detail, you will begin to develop criteria to detect what needs to be documented. Experience throughout different projects and situations will help you improve and polish your style. No one was born with an instruction manual under their arm, you’ll have to write it down. Good luck!
And… thanks for reading. 😉
