Documents
Writing sentences and paragraphs is only part of creating effective documentation. The bigger challenge is organizing all those paragraphs into a coherent, useful document.
How do you organize a large collection of information into a cohesive document or website? Or how do you reorganize an existing messy document or website into something approachable and useful? The following tactics can help:
Write for Your Audience
Answering these questions will help you determine the content of your document:
Who is your target audience?
To write effective documentation, start by identifying your audience’s roles, such as software engineers, scientists, or students. People in the same role often share basic knowledge and skills, which helps you tailor your writing. For example, software engineers usually understand programming concepts, while non-technical roles may not.
However, roles alone are not enough. Consider their familiarity with the topic. For example, engineers on one project may lack knowledge about an unrelated project, and specialists in one field may have only a basic understanding of another.
Time also matters. Skills may fade without practice, while experience grows over time. Always adjust your writing based on both the role and the knowledge level of your audience.
What is your target audience’s goal? Why are they reading this document?
Define what your audience needs to learn or do to achieve their goals. For action-required documents, like tutorials or how-to guides, outline specific actions, such as:
Filtering data using an API
Troubleshooting a system error
For conceptual documents, like references or explanations, focus on what your audience needs to understand, such as:
Key advantages of a product
Technical principles behind a system
Ensure the content aligns with the purpose of your document.
What do your readers already know before they read your document?
Effective documentation bridges the gap between what your audience already knows and what they need to know. Avoid the “Curse of Knowledge,” where experts assume others understand their level of expertise. Explain basic concepts without assuming prior knowledge and avoid team-specific jargon unless it’s universally understood by the audience.
What should your readers know or be able to do after reading your document?
Define clear outcomes for your documentation. For action-required content, like tutorials or how-to guides, specify the tasks your audience should be able to perform, such as installing software or configuring tools. For conceptual or informational content, highlight the key insights or knowledge your audience should gain, such as understanding a system’s architecture or recognizing trade-offs between design choices. Align your content with these objectives and structure it to guide readers effectively.
Adapt Your Writing Style to the Document’s Purpose
Documentation typically falls into one of four categories, each with a specific purpose and writing style. Adapting your writing style to match the purpose of the document ensures clarity and effectiveness in communication.
The four categories of documentation are:
Tutorials: Learning-oriented experiences
How-to Guides: Goal-oriented directions
Reference: Information-oriented descriptions
Explanations: Understanding-oriented discussions
Tutorials
A tutorial is a lesson designed to guide a learner through a hands-on experience. Tutorials are practical and interactive: the learner performs actions under the guidance of an instructor or structured steps. The goal is to build skills and confidence by completing a meaningful task.
Key Features:
Step-by-step guidance
Beginner-friendly language
Focus on achieving a specific, practical outcome
Examples:
Let’s create a simple game in Python.
Step 1: Install Python.
Step 2: Write a basic “Hello, World” program.
Step 3: Add game logic to create a number-guessing game.
Pro Tips: Avoid overwhelming the learner with technical explanations. Instead, provide minimal context and link to further reading if necessary.
How-to Guides
A how-to guide provides actionable steps to solve a real-world problem or accomplish a specific task. It assumes that the user is competent in the subject area and seeks guidance to complete a goal efficiently.
Key Features:
Task-oriented with clear instructions
Concise and to the point
Written for users who are already familiar with the basics
Examples:
Troubleshooting: How to resolve deployment errors.
Pro Tips: Focus on the task. Avoid including background theory or detailed explanations; these belong in other types of documentation.
Reference
Reference material is a source of accurate, complete, and neutral information. It provides facts and descriptions that users can rely on to perform their tasks correctly. Reference documentation is not action-oriented but serves as a repository of knowledge.
Key Features:
Objective and fact-based
Comprehensive and reliable
Free from interpretation or opinions
Examples:
API references, such as API reference for Non-volatile storage library
The Register section in a Technical Reference Manual, such as ESP32 Technical Reference Manual
Pro Tips: Structure reference material for easy lookup. Use tables, headings, and indexes to help users find the information they need quickly.
Explanations
Explanatory documents provide context, background, and a deeper understanding of a subject. They answer “why” questions and help users see the bigger picture by connecting concepts and ideas.
Key Features:
Contextual and narrative-driven.
Open to interpretation and discussion.
Focused on understanding rather than action.
Examples:
Why secure communication matters: The benefits of using HTTPS for encryption.
Exploring concepts: The principles of object-oriented programming and their applications.
Pro Tips: Avoid overloading tutorials or how-to guides with detailed explanations. For instance, instead of embedding a long discourse on HTTPS in a tutorial, include a simple note “Here, we use HTTPS because it’s safer.” Then link to a detailed article like Secure Communication Using HTTPS Encryption for users who want to learn more.
By tailoring your writing style to the purpose of the document, you help your audience achieve their goals effectively, whether they are learning, solving a problem, looking up information, or deepening their understanding.
Organize Your Documents with Outlines and Introductions
This section suggests some techniques for planning a longer document, including creating an outline and drafting an introduction. After completing the first draft of a document, you can review it against your outline and introduction to ensure you haven’t missed anything you originally intended to cover.
Outline a Document
Starting with a structured, high-level outline can help you group topics and determine where more detail is needed. The outline helps you move topics around before you get down to writing.
There is no standard approach to writing an outline, but the following guidelines provide practical tips you might find useful:
Before asking your reader to perform a task, explain to them why they are doing it.
Keep steps simple and focused. Limit each step of your outline to a single concept or task.
Present information when it is most relevant to your reader. For example, don’t include the history of a project in the introductory sections if the reader’s immediate goal is to set up a tool. Instead, link to the history in a “Further Reading” section.
Consider explaining a concept and then demonstrating how the reader can apply it either in a sample project or in their own work. Documents that alternate between conceptual information and practical steps can be a particularly engaging way to learn.
Before you start drafting, share outlines with contributors for feedback. Outlines are especially useful if you’re working with a team of contributors who are going to review and test your document.
Introduce a Document
If readers of your documentation cannot find relevance in the subject, they are likely to ignore it. To set the ground rules for your users, we recommend providing an introduction that includes the following information:
What the document covers and does not cover.
A good document begins by defining its scope. A better document additionally defines its non-scope—the topics not covered that the target audience might reasonably expect your document to cover. Scope and non-scope statements benefit not only the reader but also the writer. While writing, if the contents of your document veer away from the scope statement (or venture into the non-scope statement), then you must either refocus your document or modify your scope statement. When reviewing your first draft, delete any sections that don’t help satisfy the scope statement.
Summarize key points at the start.
Imagine that your peers might only read the first paragraph of your document. Therefore, ensure that the start of your document answers your readers’ essential questions. For example:
“This guide covers installation, configuration, and basic troubleshooting of Software X. By the end, you will be able to set up Software X and customize it for your environment.”
What prior knowledge you expect readers to have.
Let readers know what they should already understand. For example:
“This guide assumes familiarity with basic command-line operations and an understanding of network configuration.”
Provide Clear Navigation
Providing clear navigation and signposting ensures that readers can easily locate the information they need and confidently progress through your documentation. Effective navigation helps readers stay oriented, access related topics, and resolve issues without frustration.
Tips for Creating Effective Headings
Prefer task-based headings.
Headings should describe tasks or goals the reader is trying to accomplish, not just concepts or tools. Task-based headings resonate more with readers because they directly address what they want to achieve.
Example:
Imagine you are documenting the process of building and flashing a firmware project for the ESP32. To do this, users need to run the build commands once the ESP-IDF environment is set up.
Avoid
Use headings that focus on tools or concepts, which might confuse readers unfamiliar with the terminology. Such as:
Running the `idf.py build` Command
Better
Use headings that describe the goal or task to make it clear and actionable. Such as:
Building and Flashing Firmware on ESP32
Provide context under each heading.
Always include a brief introduction or context beneath headings. This orients readers and helps them understand why the section is relevant.
Avoid
Placing a level-three heading immediately after a level-two heading without any explanatory text.
## Building and Flashing Firmware on ESP32 ### Running the `idf.py build` Command
Better
Include a short introductory paragraph.
## Building and Flashing Firmware on ESP32 To build and flash firmware for the ESP32, use the idf.py tool once the ESP-IDF environment is set up. The following steps guide you through the process. ### Running the `idf.py build` Command Run the command `idf.py build` to compile the project and generate the firmware binary.
Use consistent and meaningful titles.
Ensure that headings follow a consistent format and use language that aligns with the reader’s familiarity. Avoid jargon unless your audience is well-versed in it, and explain terms when first introduced.
By providing clear navigation, you empower your readers to find the right information at the right time, making your documentation more effective and user-friendly.
Disclose Information Progressively
Learning new concepts, ideas, and techniques can be a rewarding experience for many readers who are comfortable reading through documentation at their own pace. However, being confronted with too many new concepts and instructions too quickly can be overwhelming. Readers are more likely to be receptive to longer documents that progressively disclose new information to them when they need it. The following techniques can help you incorporate progressive disclosure in your documents:
Explain new terminology and concepts near the steps that use it.
Break up large blocks of text with lists, tables, or diagrams where appropriate.
Break up large series of steps. If you have a particularly long list of complicated steps, try to re-arrange them into shorter lists that explain how to complete sub-tasks.
Start with simple examples and gradually increase complexity. For example, in a tutorial for creating forms, start by explaining how to handle text responses, and then introduce other techniques to handle multiple choice, images, and other response types.
Conclusion
Organizing documentation effectively is key to ensuring that it meets the needs of its audience. By writing for your audience, adapting your style to the purpose, and providing clear navigation, you can create documentation that is both accessible and impactful. Progressive disclosure techniques and thoughtful structuring further enhance the user experience, helping readers learn and achieve their goals efficiently. Remember to outline your document and introduce its purpose clearly to guide readers from the start. These practices collectively build a strong foundation for high-quality technical documentation.