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 updated.
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 from different areas of the project may confuse the reader and mislead them towards an incorrect perception of the product. There should be no information in the documentation that contradicts the current version of the system or process. Fixed incorrect references and 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. Without a clear structure and a logical order, people can't find what they're looking for. And when they can't find it, satisfaction with the product goes down.
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 set. 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?
Provide details on each of the key elements identified. Maintaining and developing any project is an ongoing cycle. Let’s consider the critical aspects related to our topic.
Prompt fixing of errors
The detected bugs should be promptly fixed to prevent their accumulation. Each additional bug contributes to the overall deterioration of the code base in accordance with the broken windows theory. It might also be helpful to appoint a person responsible for maintaining and constantly developing the user knowledge base.
Updating of information
This section should always contain relevant information. When changes to the product under development occur, they must be reflected in the documentation right away. It is also necessary to periodically check the completeness and relevance of the information and the correspondence of the documentation to the established requirements. A procedure for updating and maintaining the document should be worked out and established, which would function when changes to the product occur.
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.
Write a policy for your team, and then make sure it actually becomes part of how they work. The policy is what gives everyone a consistent approach to writing instructions, manuals, and other technical documentation. And it matters that everyone involved knows what they're responsible for and sticks to the same quality standards — otherwise you get a different result from every writer.
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 enables users to find answers to their questions and reduces the load on the support team.
Summary
Ignoring the broken windows theory while writing technical documentation may have some severe consequences. Such outcomes include the growth of support service costs, a company’s image damage, and the organization’s overall performance decline.
Correcting accumulated errors in an already existing project is a tiresome but necessary process. When you begin to create a knowledge base or list of instructions for your product, it seems reasonable to write the project in a special program since the beginning.