Applying the broken windows theory to technical writing

Dennis Crane

Broken windows theory is the concept that small irregularities left unattended can lead to more serious problems. Imagine that user documentation is a building. And typos, inaccuracies, and outdated data are broken windows. What happens to that building if no one does the repairs? Isn't it paradoxical that a seemingly insignificant element such as an error or a typo can lead to serious problems in understanding the product?

In this article, you will learn how to keep your project up to date and avoid project obsolescence.

Signs that your documentation is out of date

Let's take a look at what might be the first sign that your user manual is running low and needs to be upd ated.

Grammatical and punctuation errors

Writing documentation with grammatical and punctuation errors and typos can give the user the impression that not only the current topic, but the entire document is sloppy. This can lead to a decrease in confidence in the product and make it difficult to use.

Inconsistencies, factual errors

Conflicting information in different parts of the project can confuse users and position the product incorrectly. There should be no discrepancies between what is described in the documentation and the actual state of the system or process. Correct broken references and remove (upd ate) outdated information.

Here are some typical examples of inconsistencies:

the user manual describes a function that was removed from the latest software version;
incorrect equipment parameters are specified in the technical specification;
incorrect contact numbers are indicated in the wiring diagram;
an algorithm is described that does not correspond to the implemented code.

Lack of updates to technical documentation

Without updates, documentation becomes outdated and useless. As a result users look for information in other sources or ask for help from the support team, thus increases the workload of the customer service department.

Fuzzy structure of technical documentation

The structure of technical documentation should be clearly thought out. If there is no clarity or logical sequence, it will be difficult for users to find the answer to their question. Customer satisfaction with your product will decrease.

Many documentation programs facilitate writing by offering a structure prepared in advance. For example, in Dr.Explain, the user starts working on a document in which the initial hierarchy of topics and subtopics with headings is already se t. They are displayed in the program in the topic tree. This makes it much easier to get started, especially if you are writing such a project for the first time.

What will help to avoid obsolescence and properly develop documentation?

Maintaining and developing any project is a continuous process. Let's look at the key aspects in the context of our topic.

Correcting errors quickly

Detected bugs should be fixed as soon as possible to prevent them from accumulating. Every bug left behind accelerates the effect of the broken windows theory. Assign a person responsible for keeping the user knowledge base up-to-date and evolving.

Keeping information up to date

The documentation should be updated regularly to keep it up to date with the current version of the product. As soon as changes appear, you should write about them immediately. Conduct checks for relevance, completeness, and compliance with standards. Develop a clear update process when changes are made to the system.

Clear structure

Documentation should have a clear and logical structure so that users and staff can easily navigate through it.

Feedback

It is important to collect feedback from customers and use it to improve your project. Feedback helps to identify errors and mistakes.

Process automation

Implement a version control system to track changes and be able to restore previous versions. Use specialized tools for creating, editing and publishing. There are both online services (SaaS) and desktop applications for this. We wrote about how to choose a program for writing user documentation, as well as the advantages and disadvantages of SaaS applications and desktop software in this article.

Templates for documentation

The use of common standards and templates for program documentation helps to ensure its uniformity and quality. For example, Dr.Explain has everything you need for a quick start. These are three blanks of the most popular projects:

Corporate knowledge base;
Software user guide;
Web-service user manual.

Interaction between documentation authors and developers

Close cooperation between documentation authors and developers allows to identify and correct inconsistencies in a timely manner.

Training of documentation authors

Documentation writers must have the necessary knowledge and skills to create a quality user knowledge base. Train people who write documentation to improve the quality of the materials.

Create a writing policy for your employees and instill in them a culture of working to it. This is a guide that provides a systematic and consistent approach to creating quality instructions, manuals and other technical documentation. It is essential to ensure that all employees involved in the documentation process understand their roles and responsibilities and adhere to uniform quality standards.

Benefits of applying the broken windows theory

The steps listed above will not only help to facilitate the work on the document in technical terms, the psychological moment is important as well, when due to compliance with quality standards the mutual understanding and interaction of the team as a whole improves. This is what can be achieved by correcting deficiencies in a timely manner.

Prevent accumulation of “technical debt” in documentation

Setting a precedent: uncorrected errors may se t an example for other authors who decide that similar inaccuracies are acceptable. This can lead to further degradation of documentation quality.
Deterioration of understanding: the accumulation of errors makes it difficult to understand a product or system, which can lead to additional time and resources spent on troubleshooting.

Motivation to support quality

Creating an atmosphere of attentiveness: when documentation is neat and thorough, it creates an atmosphere in which authors strive to maintain a high level of quality.
Respect for the user: well-developed documentation demonstrates respect for the reader, showing that their time is valuable.
Pride in their work: authors who produce quality documentation feel a sense of pride in their results, which motivates them to keep improving.

Improved cooperation in the team

Shared standards: carefully calibrated standards and templates for documentation create a consistent style and increase readability.
Shared responsibility: when all team members adhere to common standards, it fosters a sense of shared responsibility for the quality of documentation.
Conflict reduction: clear rules and standards help avoid disputes and disagreements when writing documentation.

Improving operational efficiency

Reduced support costs: quality documentation reduces the number of questions from users and reduces the time spent on support.
Accelerate development: clear and understandable documentation helps new developers get up to speed with the project and start contributing productively.
Improved communication: well-written documentation facilitates better communication between developers, testers, and other project participants.

Improved user experience

Clear and easy-to-understand documentation makes it easier for users to learn the product and increases their loyalty.

Reducing the burden on the support team

High-quality documentation allows users to find answers to their questions on their own and reduces the load on the support team.

Summary

Ignoring the broken windows theory when writing technical documentation can lead to serious negative consequences. These include an increase in support service costs, a deterioration of the company's image, and a decrease in overall performance.

Correcting accumulated errors in an already existing project is a labor-intensive but necessary task. If you are just starting to create a knowledge base or a list of instructions for your product, it makes sense to write the project in a special program from the very beginning.