Common Documentation Mistakes
Addressing these common mistakes in documentation is essential for creating more effective and user-friendly content.
Being wordy
Engineers may include too much detail, leading to overwhelming or inefficient documentation. The key is to communicate clearly without overloading the user with information.
Why it matters: Concise content is easier to understand and follow, reducing cognitive load and minimizing user frustration. Users often skim documentation, so focusing on the most critical information helps them find what they need quickly.
Original
To get started with using the new feature, the first thing you need to do is open the application and navigate to the settings menu, which you can find by looking at the top right corner of the screen. Once you are in the settings menu, you should look for the section that says 'New Feature Setup'. Click on that section, and you will see a button that says 'Start Setup'. Click on the 'Start Setup' button to begin the process. Follow the on-screen instructions to complete the setup of the new feature.
Revised
- Open the application.
- Navigate to Settings (top right corner).
- Select New Feature Setup.
- Click Start Setup and follow the on-screen instructions.
Why this is better: Breaking down the steps into a simple list makes it easier to follow and eliminates unnecessary phrasing that can confuse the user. Engineers often struggle with verbosity, so it is critical to show them how to distill instructions into actionable items.
Using jargon and technical terms
Engineers may assume users have the same level of technical knowledge, which can lead to the use of complex terminology without explanation.
Why it matters: Not all users have the same technical background. Simplifying or explaining jargon ensures that documentation is accessible to all users, not just those with deep technical expertise. This prevents confusion and allows more users to engage with the product.
Original
The microservices architecture utilizes a service mesh to handle inter-service communication and observability.
Revised
Our application uses a network layer (service mesh) to manage communication and monitoring between different services (microservices).
Why this is better: Here, the term "service mesh" is simplified with an explanation ("network layer"), helping users unfamiliar with the jargon. Engineers often resist simplifying, fearing loss of precision, but this approach maintains accuracy while improving clarity.
Focusing on too much detail
Engineers often include unnecessary technical specifics that aren't relevant to most users. This leads to information overload, detracting from the primary message.
Why it matters: Users don't need every technical detail. Focusing on key actions and critical information makes documentation easier to navigate and understand.
Original
The server is running on a distributed architecture with node clusters set up to scale horizontally, and you should also note that the system uses a multi-tier architecture for database operations.
Revised
The server can scale based on usage and efficiently manage multiple layers.
Why this is better: The revised version removes unnecessary technical details that users might not need to understand. Engineers should first focus on delivering essential information and, if necessary, link to more detailed references.
Lack of structure and organization
Documentation that lacks clear structure is difficult to navigate. Engineers might write in a stream-of-consciousness style without considering how users will interact with the content.
Why it matters: Organized content lets users find information quickly. Headings, subheadings, and logical flow help users follow step-by-step processes more easily.
Original
First, you need to install the required dependencies. Next, configure the application settings. Finally, start the application. Before doing any of these steps, ensure your system meets the minimum requirements.
Revised
- Ensure your system meets the minimum requirements.
- Install the required dependencies.
- Configure the application settings.
- Start the application.
Why this is better: Breaking up the steps into a clear list with proper order makes it easier for users to follow. This structure reduces cognitive load and prevents confusion.
Inadequate explanation of concepts
Engineers often assume users already know certain technical concepts, leading to incomplete explanations.
Why it matters: Providing sufficient context ensures users at all levels can understand the instructions. Users might be confused without adequate explanation, leading to mistakes or incorrect implementations.
Original
Initialize the repository.
Revised
Initialize the repository by running git init, which sets up the necessary files to track changes in your project.
Why this is better: Adding context explains why this step is necessary and what it accomplishes, which is often missing in technical documentation.
Using screenshots without text instructions
Screenshots can be helpful, but relying on them alone can create issues if the UI changes or if users require more detailed information.
Why it matters: Screenshots quickly become outdated, whereas written instructions provide more clarity and are easier to update.
Original
Revised
Navigate to Settings (top right) > Account > Manage Settings. For reference, see the image below.
Why this is better: The revised version includes text instructions in addition to the screenshot, ensuring users can follow along even if the UI has changed.
Using non-descriptive hyperlink text
Engineers often use vague terms like "click here" for links, which doesn't provide users any context about where the link leads.
Why it matters: Descriptive link text gives users context about what they are clicking, improving usability and accessibility.
Original
For more information, click here.
Revised
For more information, see the API Setup Guide.
Why this is better: By using descriptive link text, users can understand the purpose of the link before clicking. Engineers should recognize that vague links frustrate users and can reduce efficiency.