Writing
You've analyzed your audience, you've gathered your materials, done your research... now it's time to actually write.
Following a few simple principles can mean the difference between an unreadable wall of text and a sleek, easy to parse set of instructions.
Technical writing should be precise and easy to understand. Follow these guidelines:
🗣️
Use plain language.
Choose words that are simple and familiar to your readers. You are here to inform, not to show off your vocabulary.
🚫
Avoid jargon.
Sometimes you can't escape jargon, especially if you are writing about highly technical topics, but make sure to provide explanations or definitions to help readers understand.
🧍♀️
Prefer active voice.
Active voice makes sentences more direct and makes it clear who or what is doing the action.
🫵
Use second person.
It's "you", not "the user". You are talking directly to the people who will be following the instructions.
⏳
Use present tense.
Present tense makes actions feel immediate and actionable. Avoid "should", though! It implies something is supposed to happen, but may not, which can make users lose confidence.
🤯
Break down complex concepts.
If a concept is difficult, provide examples, analogies, or step-by-step explanations to make it easier to understand.
🌍
Write for a global audience
Ensure all users, including non-native speakers, can easily understand the documentation.
Avoid idioms and slang that might not translate well or be universally understood.
🧑🤝🧑
Cultural Sensitivity
Pay attention to variations in date formats, units of measurement, and symbols across different regions.
Use culturally neutral examples to avoid unintended offense or confusion.
Readers want to find answers quickly, without obstacles. Follow these guidelines:
- Use short sentences and paragraphs. Technical manuals are not novels! Aim for sentences with 20 words or fewer for easy readability.
- Get to the point quickly. Avoid lengthy introductions or unnecessary background information.
- Eliminate unnecessary words. Be direct and remove filler words that do not add value.
- Avoid repetition. If something has already been explained, don't restate it, just point readers to the prior explanation.
- Avoid unnecessary explanations. If your audience is familiar with certain concepts, don’t over-explain them. Assess their level of knowledge and adjust accordingly.
At a micro level, a well-structured page is easier to follow and helps users find information quickly. At a macro level, Information Architecture dictates how the entire documentation is organized. Both aspects are crucial for making your documentation effective!
Follow these principles when creating the structure of a page or topic:
- Use headings and subheadings. Clearly labeled sections help readers navigate the content efficiently.
- Group related information. Keep similar topics together and follow the same structure everywhere. For example, if you are documenting a user interface, always have a topic that describes the window, followed by a topic that describes the available buttons. Don't mix the descriptions of the buttons with the descriptions of the tasks.
- Present information in a logical sequence. Document steps in the order they should be performed. If a task has prerequisites, make sure to mention them before starting to explain the task.
- Use numbered lists for step-by-step instructions. Numbered list indicate to readers that they should follow the instructions in order.
- Use bullet points for options. Bullets help break up text and make critical information easier to scan. Use bullets where the order of the items doesn't matter.
- Tables and charts enhance understanding. When presenting complex data, visual elements like tables, charts, and graphs can improve clarity and retention.
Images, diagrams, and screenshots can clarify instructions and make content more engaging. Follow these guidelines:
- Ensure the visuals are high quality and relevant. Avoid low-resolution or badly cropped images. Full-screen screenshots help the users orient themselves, but if you need to focus on a part of the screen crop the image carefully so that the results looks professional.
- Label images and provide captions. A brief description helps the reader understand the purpose of the visual.
- Use callouts to highlight important elements. Marking specific areas of an image can guide the reader’s attention to key details. Use software that allows you to save the callouts as a separate layer, so you can update them if needed.
- Don't use too many images. Images should support the written content rather than replace it entirely. Always provide text explanations for key points.
- Plan for screenshot maintenance. If you are documenting a user interface, odds are it will eventually change and you will need to replace all the screenshots. Keep this in mind when deciding whether or not to insert a screenshot - sometimes plain text is just fine.
- Use diagrams to explain complex processes. Flowcharts and infographics can make complicated procedures easier to understand.
A consistent writing style improves readability, so a style guide is a must. Follow these guidelines:
- Choose an existing style guide or create your own. The following section has some ideas and Reference: Style Guides lists the most popular guides you can choose from.
- Use standard formatting for headings, punctuation, lists, and so on. It's essential for the professional aspect of your documentation.
- Use consistent terminology. Never refer to the same concept with different words - it will just cause mental load.
- Consider defining templates for frequently used document types. They don't have to be very formal - even a checklist of questions to ask is useful. The Good Docs Project has an extensive (and ever-growing) collection of templates you can use and adapt.
Adopting a publicly available style guide is the simplest way to ensure consistency and standardization in your documentation, but a single style guide will never cover all of an organization's needs.
The best way to solve this problem is to use a hierarchy of guides:
- First, define internal guidelines that describe word usage, branding, tone and voice specific to your company or product. Internal guidelines should contain only things that are too specific to be included in a general-purpose style guide. For everything else, it's not worth the effort to reinvent the wheel.
- For general technical writing matters, use the technical writing style guide most appropriate for your industry - for example, the Microsoft guide for software that runs on Windows or the Red Hat guide for open source. You can find an overview of the most popular style guides in Reference: Style Guides.
- For general grammar or language queries, use the general-purpose style guide that best aligns to your chosen tone of voice. The Chicago Manual of Style is a popular one.
- For spelling, use a standard dictionary, such as Merriam-Webster, for American English.
Always remember: consistency is the most important. Don't agonize over a guide choice and don't overanalyze word usage.
If the guides don't give a definitive answer, just make a choice, document it in the internal guidelines and use it consistently.
The work does not end after you've written the documentation. The first draft is rarely the best. Follow these guidelines:
- Cut out anything that does not directly contribute to the main message. Re-read the Be Concise and Focused principles and make sure they are applied throughout.
- Check for inconsistencies. Proofread your text and fix any mistakes in terminology, spelling or formatting.
- Review the document as a whole. Ensure that sections flow logically and that any references to previous content are correct and consistent.
- Check consistency with the product you are documenting. Before sending the text off for review, make sure it matches the final version of the interface or physical product.
The hard part is done, but there are still some stages until you can deliver the documentation to your end-users.
The next one:
- Reviewing. Whether it's just proofreading from a coworker or a thorough review from a business analyst, it's always a good idea to have another pair of eyes on your work.
