Danny Briskin, QA Consultants Senior Automation Engineer
The issue
In any project, whether it is software development or testing or support, the importance of adequate and up-to-date documentation should not be underestimated. If a project relies only on “sacred knowledge” of its personnel, it is doomed. If the documentation exists but is not up to date it will lead to imminent errors in development, testing or support routines. If documentation is up to date but lacks details and links to other documents it will force project personnel to spend longer time to figure out obvious issues, and that can increase the total project budget. If documentation exists and is regularly updated but has questionable consistency and reliability (i.e., there are several points of truth) it will lead to useless work done with mistaken basis and possible conflicts in the team.
What is to be documented
The first precondition is: there must be documentation in the project. Don’t join a project without it. Well, if you ought to, do it yourself. Be 100% sure it will pay you and your team out very soon. A plain text file, saved on your local PC with some part of documentation is better than nothing.
Artifacts
Whatever your project is working on, it should have a document. Whether it is database table, class or method in the code, a server to maintain, a utility to run - everything. Use built-in capabilities of collaboration system you use or create your own documents. Use cross links to other documents to tie up the documentation and navigate through it.
Processes
Create step-by-step instruction for all processes manual execution routines. Create description for automatic processes (inline it in scripts if possible) to be able to repeat it manually. Don’t hesitate to include screenshots, even for obvious operations, sometimes those instructions are executed in a stressful environment by not highly trained personnel.
Environments
Write out all variable values related to each environment you use to be able to recreate it if needed. Collect all scripts needed to be run in the environment, prior to start usage.
Thoughts
Create a blog. Be able to record down your thoughts about artifacts, processes, etc. Put down any ideas you want to implement in the future. Those little documents can be easily transformed into user stories and tasks.
How to document
Don’t assign a single person to be responsible for documentation creation. Encourage all team members to take part, it will not only increase involvement but can strengthen team knowledge and boost information exchange between colleagues. Add a possibility to vote for the best documents, people should be recognized for their efforts.
Introduce a versioning system into your documentation project. It is always useful to return to one of the previous versions of an instruction and compare it with the current one. Besides history, you can always track changes by author.
Discussion is an important part of human culture, use it wisely in documentation. Add a possibility to comment all documents (and comments as well) but be careful, don’t turn comments into more valuable things than the document itself.
Take care of sensible information. Be able to share documentation with those who have proper access and hide it from others. Make sure that relevant stakeholders have access to the documentation they need.
It is a clever idea to have a technical writer role in the project. Not all specialists are experts of words and taking in account language and cultural diversity in contemporary projects, the documentation they produce could be hardly readable. Technical writer can polish the documentation and make its appearance standardized.
Tools
- A free MediaWiki tool or any standalone or hosted Wiki-like tools. With all the power of Wikipedia, you can create and maintain highly customizable documents. There are comments and discussions, and a lot of plugins. Unfortunately, version control and user management are very primitive. The main drawback of the system is lack of native links to other collaboration tools (like task management, version control system, etc.)
- Atlassian. Well-known Atlassian tools for IT projects like Jira and Bitbucket. There is also a dedicated tool: Confluence but even with a basic Wiki, coming with Bitbucket repository, you can achieve impressive results in documentation.
- Mictrosoft Azure a paid tool from Microsoft with all its excellence.
- GitHub a built-in documentation system in Git repository is not enormously powerful but is very handy (yes, this article was created in that tool)
- Gitlab - another version control system with documentation tools onboard
Summary
Create and review and maintain your documentation every time! “Boring and useless” work can turn your project from disaster to success. Your team members will be grateful for your efforts and even if you leave the project, future generations will be excited to have such a farsighted predecessor.