The article series “Tester Tea-Time” covers topics and issues that our testers face every day and that are, above all, recurring. We should like to use these articles to explain such phenomena, to find solutions and to encourage discussions and new mindsets. In testing, we can learn a lot from each other by observing our behaviour in our daily lives!
Moderator: Welcome to Tester Teatime! In the interviews with testers of ZEISS Digital Innovation (ZDI), we regularly address interesting topics. Today, we shall be dealing with the issue of documentation in day-to-day project work. Our guest is Sandra Wolf (SW), tester at ZDI.
Sandra, why do you call documentation “eternally unloved”?
SW: The daily work of a tester is often stressful, and we often work under high pressure. We make the experience that for some tasks little or no time remains. Among others, this applies to documentation. It is readily forgotten or postponed – hence the attribute “eternally unloved”. This is due, among other things, to the fact that proper documentation is time-consuming. Time is precious. In modern society, it is usually dedicated to the most critical tasks of the daily work routine. Today, we shall look into the effects of good documentation on the daily work of the testers and why we should change our mindset regarding the importance of documentation. Because one thing is certain: It deserves to be firmly established in our life as testers.
Moderator: Where in the day-to-day project work do testers encounter the topic of documentation?
SW: In our daily work, each tester is confronted with the need to document test results or deviations. To this end, it is important, among other things, to collect all information other team members may need. But how about documentation for the purpose of knowledge transfer? In particular, it can be very important to document tips and technical know-how concerning software, especially if it is very complex. Of course, scope and design depend on the specific project. Is any there documentation available from conception or the customer? This may be used as a starting point. If not, all team members should have the ambition to develop such a documentation step by step. Many will now think that this is way too much effort. That there is no time for this during the daily routine. We testers should now stop and consider the positive effects of a well-made documentation on our day-to-day project work and on the daily routines of our colleagues.
Moderator: What exactly are the positive effects of an adequate documentation?
SW: Documentation is a prerequisite for knowledge management, i.e. for the development, exchange and preservation of knowledge. If knowledge management is well-organised, arising questions are usually first researched in the documentation. This saves meetings, calls and time. A great amount of relevant information is available from one central source – forming the basis that permits colleagues to work independently. This eliminates for example recurring questions from team members, and it makes the on-boarding of new colleagues a lot easier. Such a knowledge base can also support the testing of certain complex application areas by documenting specific tests or by providing technical background knowledge. Researching these requirements and tips can also speed up the actual testing.
All examples described save time that we think we don’t have to document something. Of course, it takes a high initial effort to build up such a knowledge base, but the yield is a valuable tool that saves time in the long run and that increases the efficiency of your day-to-day work and the testing process.
Moderator: Does this mean that investing into documentation time always pays off for the project?
SW: Yes, on the whole, I believe that investing into the time and resources necessary to develop a knowledge base pays off. The return of this investment is again time which is always short in your daily work. The time saved can be dedicated to other tasks. Well-organised knowledge management is a prerequisite any project if you wish to improve efficiency.
Moderator: How can knowledge management be introduced to or implemented into the project? On this issue, we ask Max Wielsch (MW), developer at ZDI. Max, what can you tell us about this issue?
MW: In my project, a very comprehensive wiki documentation in Confluence is used. It is amended by code-based documentation that is integrated into the wiki. I have created this knowledge base together with my team. We already used documentation in the past, however, this was restricted to two Word files, and the sources of knowledge were no longer available at that time. Since we support a very complex platform comprising several micro-services – mostly on the technical side – it was clear to us that a comprehensive documentation will yield a decisive value-added.
Moderator: How exactly did you master this tremendous task? Can you give other colleagues some tips along the way?
MW: My objective was to structure the existing chaos. Of course, creating a well-made documentation is a job that’s never done. Throughout all stages of the process, documentation requires continuous and adequate maintenance to ensure correct knowledge transfer. I started off by obtaining an overview and then decided to use arc42 as a structure template for the wiki. The tool was then adjusted to our project. Since the structure of our system is highly complex, our documentation is structured accordingly. Individual modules or elements may in turn have a new sub-structure. Also, we have different types of documentation areas: The documentation of the architecture containing a technical as well as a functional documentation, and the operating documentation. These areas are all located in the wiki. Related topics are linked to facilitate knowledge exchange and development. All these pages for example explain processes and contain references to technical descriptions in glossary entries or explain the configurations of a module. We also implement specific filters of the issue tracker (Jira) to make relevant bugs or upcoming stories easily visible. Context is simply everything!
Moderator: That sounds elaborate but also interesting. Did the implementation of such a documentation yield any benefit for you?
MW: For sure! We already gain time by being able to refer questions from technical departments, operations or other stakeholders to the corresponding pages. In addition, the documentation structure is the perfect tool for handing over new software versions to operations. We use, for example, special fields in our stories and bugs that we can list in tables in specific release wiki pages. We can present various aspects of the change. On the one hand, we have release notes for the communication to the stakeholders, on the other hand, we us so-called “ops notes”. These allow us to provide targeted information about operating a new function. Of course, they include corresponding links to pages of the operating documentation. As you can see, documentation is used throughout the entire process, from planning to operations. Eventually, we can always provide proof of having handed over changes to the software version completely and that operations have been provided with everything they need to know.
Moderator: Wow, this is a really good example of the benefits documentation can yield in a project. Do you also see any drawbacks that should be considered?
MW: Yes, of course, as always. Complex documentation requires maintenance and care. It must be kept up to date. Outdated, obsolete information must be removed. Also, it is not always easy to adhere to the document structures. Maintaining the content requires the exactly right level of detail to be identified so that only the information actually necessary is provided and that anything dispensable is removed. A cost-benefit analysis is always mandatory, and it greatly depends on the context of the project. With regard to adherence to structure: Actually, the entire team is responsible for the documentation. However, as is often the case, you sometimes need a person in charge to supervise, check and make adjustments. This can be particularly helpful for large projects or wherever a great number of developers is involved to make sure that the documentation follows a straight line. Once all developers have internalised the documentation’s principles and apply them correctly, less control may be exercised. However, this depends greatly on the project, i.e. the team’s structure, capabilities and areas of expertise.
Moderator: This is a good closing statement. Thank you, Sandra and Max, for sharing your insights. In short, we see that a good documentation can pay off for the project, and that the decision for its structure depends on the project’s framework conditions. This unloved topic deserves more attention as it has the potential to save time in the long run and to make team work more efficient. As defined in standard ISO 24765, documentation is an intrinsic aspect of product quality and therefore, underlining its importance, of the quality of the software as well.
In the following articles, we will address other issues from the daily lives of testers and discuss possible solutions for these.
This post was written by:
