Hi, my name is Irina Isai, I am a technical writer at the WePlay Esports media holding. I want to share my experience of conducting a tech documentation audit and the creation of product documentation for several products of our company at once. This story will cover the experience of my previous projects, there were also a lot of interesting and useful things.
My history of working with WePlay Esports began with the task exactly like this, i.e. to audit the tech documentation. Over the past year, I have heard many times from various companies about their craving to do it. Some wanted to hire a full-time technician to conduct an audit and then implement the developed recommendations, while others only wanted to consult on the process.
So I welcome team managers, technical writers, product owners to spend the next 15 minutes together. Let's talk about the audit of technical and product documentation: what it is, why to do it, and how best to conduct it. The topic is quite new and little researched, it is not discussed much in articles and comments of the tech writing community.
And I invite developers’ and testers’ teams to join the conversation. If you are infuriated by technical writers who constantly talk about the documentation, distract you from your work, ask where your notes are, try to force you to document something, you may find answers to your questions or tips on how to work with technical writers.
Our conversation aims to balance two sides:
- There are no rules or standards by which documentation should be audited. There are only a few materials on this topic on the internet. Not because someone is lazy or greedy for experience and knowledge. It's just that the IT industry, in general, is very changeable, all approaches and processes change so fast that you don't have time to finish an instruction or recommendation, as you already need to write a new one. I hope that my experience will make life easier, and maybe inspire those who are going to take on this difficult task.
- Teams and company management do not consider the tech documentation audit to be an absolute necessity, they put it away for better times. Many have not even heard of it. Even the word "audit" is perceived negatively, it is a kind of "check" of work, so teams are a little hostile to such an intervention. It will be good if my words could at least change your attitude.
The Tech Documentation Audit
Let's start with the definition of terms.
An audit of product- and technical documentation is a comprehensive verification of existing documentation on the relevance, reliability, completeness, compliance with certain styles, and other pre-established criteria and requirements. The purpose of the expert or team diving into such an audit is to assess the current state of affairs, identify what is missing, and provide the necessary recommendations to address the deficiencies.
Documentation should be audited with some regularity. This is not necessarily be based on a certain period, perhaps once per version or during a change in management, development strategy, or team reboot. Much depends on the intensity of product development and the defined objectives of the audit. Usually, the audit task comes down from the top management of the company and is one of the stages of auditing all the company's products. But it happens that such a task is determined by the technical writer himself/herself or the team he/she works with, having previously defined clear audit objectives.
I often hear: “Why should one spend so much time and money on documentation? Everything works for us anyway ”.
Here are just a few reasons for that.
Onboarding. If you do not have the appropriate documentation, it may mean that pieces of expertise and product information are kept in people’s brains. They often do not have time to share their knowledge with beginners.
So instead of forcing newcomers to run around the office from workplace to workplace with a bunch of questions, it's better to have a structured guide with detailed and up-to-date information. First, the guide will make onboarding smoother, new guys will quickly grasp product information and product links if there are several. Second, it will take a huge burden off product owners.
Sale or attraction of investments. In addition to easy onboarding, companies are sometimes interested in sales, partnerships, investment. A nice appearance of a product and assuring that everything works are not enough for a potential investor or a partner. He/she must understand how everything is structured from within. And for this, you need to have the appropriate documentation that clearly and intuitively describes the product and its functional aspects.
It often happens that when you describe a product ex post facto, you can find some features that no one even knows it’s there and can not explain where it came from and how it works because no one has documented its creation. Such features can live in the product for years. This means that there will always be an invisible button or an extra line in the form on the screen, which at best has no functional load.
In general, well-prepared documentation is the "face" of the company's product and (not) unnecessary confirmation of the value of the company itself. It is also a sign of the quality of work of each team member involved in the project and the team as a whole.
Standards and approaches to the technical documentation audit
My little experience in document auditing has shown that this is a complex process with many unknowns. I studied the information online for a long time and came to the disappointing conclusion: there are still no standards and clear rules. But there are best practices and approaches. They are based on the individual and collective experience of technical writers and their teams.
The ultimate goal of the product development team and the audit technician is not to kill each other until the audit is complete. I am even a little convinced that it is still possible to create these standards and recommendations. The collective mind is a great force.
Stages and time limits
We should understand that the audit and further work on the implementation of audit recommendations will take from a few weeks to several months. Conventionally, the whole process can be divided into the following stages:
- Studying all documentation available. For the most part, it is technical and often outdated.
- Developing the recommendations to eliminate shortcomings. By the way, no one reads them, so it is better to present them orally with good visualization.
- Starting the work with the product. The study of the product itself and the development of standards for its description take place in parallel.
- Developing a single standard for writing technical documentation for all teams. This is an optional point, it cannot be avoided in the case of a large company with many individual teams, and when each team does not have its own technical writer and is forced to keep its own technical documentation.
- Forming a culture of technical writing in the company. This is my professional cherished dream. I have experience when teams did not perceive a technical writer as someone important and necessary.
So don't expect this whole story to end quickly. Here’s my story.
The first month. The technical writer compiles absolutely all documents, records, reads every guide, dictionary, policy if there is any. The task is to study everything available, to find "gaps" in the sequence, to identify the irrelevant, to develop a plan for organizing what can be organized.
That’s how I compiled the Audit Summary. Gaps, structure, language, headings, style, or its absence - everything that could have been important, was written in paragraphs.
The second month. When everything became a bit more coherent and it became clear that the “patient is alive”, I moved on to the treatment of local sores - to focus on a specific project (product) or on a specific area (team).
Here you can start making recommendations for writing new documentation, collecting terminology, and so on. From my experience, I will say that even in one team people can describe the same functionality in different ways: in English, “runglish” (Russian+English), using transliteration from all possible languages of the world. And, of course, teams love abbreviations, and this is something completely nuts.
The draft of the instruction for technical writers. I like to immediately outline the rules of the game and always say what to write, and what not to write. I do not write explanations, we discuss and agree on everything verbally. Then we have kind of a checklist for a technical writer on the most important things only.
The third month. Once we have defined the standards and approaches that are lacking and started describing them, we already have a plan of action in place to implement them.
Let me remind you, this is crucial if you have several teams, and you are a single technical writer and are not physically able to write technical documentation for each team. Therefore, our goal is to help teams keep their records well and, most importantly, to standardize approaches. So we make life easier for ourselves - the technical writer and his/her team.
At this stage, a large part of the top-level product documentation has already been processed and reduced to a single style, gaps have been filled, outdated information has been removed, and a lot of data has been collected on all products to be used in the future articles.
And this is a short introduction to the big manual, which will consist of guides, which in their turn will consist of articles… But this is not the main thing, and even the content is not the main thing, it will change more than once. The main thing is that it can already be used by anyone. I like to structure as follows: Introduction; content; sections; additional links to related articles are provided at the end of the material.
The fourth month. Standards for writing technical documentation for teams have been gradually introduced, and you can also hold additional training sessions for teams. Therefore, it is time to adjust the standards.
Yes, you read that correctly. Why adjust what you just created?
Because all teams are different. Levels of perception, trust, and ultimately the desire to change something in their work are also different. You can't use the "one size fits all" approach. But you can unify approaches so that everyone is comfortable and understands how to work. In addition, it is already possible to finalize any tasks that have been left from the third month.
And if you have several teams and several products, that are also combined in certain processes, all these four months you have to bounce between them all. Hence, at the first stage, there is a certain confusion. It is impossible to predict the structure of product documentation, what will be the titles of articles, even what should be their visual components. Each company, like its products, is very individual.
Not every team enjoys the tech documentation audit
In the perfect world, teams, having just created a new product or feature, ask a technical writer to document a new solution. Everyone benefits from this as teams receive a literally written confirmation of their work. You can even put it in your resume: here's what I’ve created, here's how it works, step by step. The company sees what its product consists of, "feels" it. And the technical writer does not need much, just the enjoyment that everything is properly documented. The price tag of all three parties only grows from the proactivity of the teams, you can take my word for it.
In the real world, you have to describe everything asap and overcome obstacles on a daily basis.
Let's be honest, no one wants to put an additional task on their shoulders, no matter how noble the purpose is. In my practice, there were teams that tried to get rid of the "unnecessary" formalization of processes, unnecessary questioning, there were even cases of complete ignorance.
It can be even more complicated if the technical writer is not in the same room with the team. And today, when the pandemic is raging and we all work remotely, the contact is reduced to the "send message" button.
My choice is to look for like-minded people.
It is impossible to persuade people with boring assurances that there must be order and that everyone will benefit from this order. But it is possible to be interested, to show that to invest a little of their time and attention now is to save hours or even weeks of effort in the not-so-distant future.
You can also add product-owners, business analysts, and project coordinators to the list of potential “supporters”. They are usually very interested in ensuring that everything in the product is laid out on the shelves. Of course, you need to do your homework, "sell" them the idea of the documentation audit in a way that they could understand its benefits, promote it as something great and beneficial for their teams.
Also, be sure to fight for the love and attention of testers and developers. They are a source of the most interesting information about products, and if you are lucky, also custodians of valuable technical documentation.
In my conversations with potential allies, I emphasize that quality documentation is an added value for the team and each specialist. The most common objections are:
- "Our value is the product we have created." I agree. But for an outside observer, it is a complex "wrapper" with the company's logo, which does not show the work of specific experts.
- "Our value is written code." I agree with that too. But for the most part, you can boast about the code to those who understand it, and only if it is not prohibited by the non-disclosure agreement. Almost no one sees or parses the code from the outside.
In both cases, documentation is an opportunity to show yourself. And if it is publicly available, it is also an opportunity for the team to justify their skills and abilities.
Sometimes a technical writer needs to use his/her soft skills, in other words, “traditional methods”: to get the right person for a walk/beer/dance. It helps set you to get on the same page.
And then it’s like in a soap opera. Teams are already used to you as a technical writer, although you continue to annoy them sometimes. They don’t throw stuff at you, and that’s already a good sign. In a little while, the technical writer’s dream will come true: they will come up with suggestions to describe something in technical documentation. And if they do not forget to invite you to their grooming meetings, then this is love!
Onsite audit vs outsource audit
Еhe tech documentation audit, like any other, can be performed by both internal and external experts. Of course, there are advantages and disadvantages, but there is no single right solution, it all depends on what goals are set by the management.
In addition, not all companies can afford to keep a team of technical writers. And sometimes external consultation is needed to improve some processes or just learn from new experiences.
An external audit is an unmistakable look at tech documentation and an opportunity to get up-to-date recommendations for the technical writer team. Even if the company does not have a technical writer, this is an opportunity to standardize documents and, consequently, increase the value of the product. On the other hand, an external audit is also a risk of disclosing information about the company's intellectual property.
For a technical writer to conduct an audit in another company is also a great advantage, from learning new processes to improving own skills.
The internal tech documentation audit is a rare phenomenon. To be honest, I haven't heard anyone do it. Of course, we do not take into account large companies with international experience, for which such processes are quite common. In my opinion, if the company has allowed itself to have a technical writer or even a whole team, then the internal documentation audit should be mandatory, conducted with a certain precision, and according to certain procedures.
The (non) financial result
I do understand those who want to measure the quality and value of documentation audit in money. But there is no direct connection with profits.
However, here are some, let’s say, control questions. How much can a company save/earn if:
- the team does not spend time onboarding new employees, introducing the product in general, or talking in detail about any feature, and spend those hours or even days on their direct work (code, testing, release, etc.)?
- a new person in the team can quickly get acquainted with the company's products, simply learn where to find the necessary information about the already created functionality?
- the support service has less workload and users will find the right answers in the documentation?
- the team have additional information on how the product of their colleagues from other teams (related functionality or product) works, and therefore coordinate and unify the processes of interconnected projects?
The list of questions can be extended because each team and company will receive its value from such an audit.
And the answer to these questions is one: well-described documentation makes life much easier for all parties involved in the creation and maintenance of the product.
In addition, in my opinion, the tech documentation audit is becoming relevant right now. A pandemic is raging around, the world is entering a new financial and economic crisis, companies are forced to rethink their processes and development strategies. the tech documentation audit helps greatly in this rethinking, and may even be a source of strategically important solutions.
Does your company conduct or plan on conducting an audit? And how is it going in your company?
Original article on
