technical Writing 101

I’ve been in the technical writing field for a few years now. Recently, I had the opportunity to contribute to AsyncAPI under Google Season of Docs. This document covers the responsibilities of technical writers, style guides, and best practices in technical writing.

A technical writer?

If you’ve ever struggled with poorly written instructions and thought, “I could write better instructions than that!”

A technical writer creates, gathers, organizes, and presents technical information clearly and concisely. They prioritize making documentation understandable and useful for users to respect their time.

Their goal is to provide information on what the reader wants to know, where to find it, and how it aligns with the existing knowledge. You must follow the following order of importance while creating documentation:

1. Correct
2. Complete
3. Usable
4. Clear
5. Consistent

First, documentation must be accurate and complete to address users’ needs effectively. Additionally, it should offer helpful solutions to user problems. Clear and consistent documentation enhances user understanding and experience.

The most crucial question in technical documentation is, “Who is the end user?”
To tackle this, consider crafting a persona—a fictional representation of your target audience. Consider the following points when creating a persona:

• Keep the developer’s goals in mind
• Expect potential challenges users might encounter
• Assess the developer’s technical skill

Additionally, ensure your documentation is accessible to the majority of the people:

• Ensure all images have “alt text” that describes the image, as screen-reading tools read the image description for some users.

Incorrect use of paragraph tags and styles can cause translation problems in documentation. To avoid formatting issues, follow these guidelines:

• Ensure all commands, file names, user inputs, and code samples are correctly tagged.
•  Avoid using spaces, tabs, or hard line breaks to create tabular formats; instead, use tables. 

Requirements

The first step in writing technical documentation involves identifying the necessary requirements. One method to achieve this is by utilizing MoSCoW, which categorizes requirements based on their priority:

• M (MUST): Describes essential requirements for the product.
• S (SHOULD): Describes a high-priority item in the product.
• C (COULD): Refers to a desirable but non-essential requirement.
• W (WON’T): Denotes a requirement that will not be implemented.

After gathering all requirements, the next step is to develop a documentation plan. Every documentation project follows these steps:

1. Gather: Collect all necessary information and resources.
2. Plan: Outline the structure and objectives of the documentation.
3. Write: Begin drafting the documentation based on the established plan.
4. Verify: Review the accuracy and completeness of the documentation.
5. Redo: Make necessary revisions or updates based on feedback and verification results.

Gathering information

Gathering information is an ongoing process that persists throughout your project. To gather information, you can:

• Read specifications and engineering documentation to understand your project
• Familiarize yourself with the product by actively using it
• Gain insights into your audience by understanding your users’ needs
• Interview subject matter experts (SMEs) to understand how the product functions

Rather than relying solely on SMEs for information, aim to develop expertise yourself. Being your own SME helps:

• Engage in meaningful discussions with the SMEs
• Verify the accuracy of information received or encountered
• Increase writing efficiency by leveraging knowledge
• Produce solid drafts that optimize reviewer time
• Ensure documentation accuracy even with limited SME review

Planning Information

Once you’ve acquired enough knowledge, it’s time to plan and structure your information. You don’t have to wait until you know everything. If you’ve never created a documentation plan before, start with the basics:

• Name of the deliverable
• What needs to be done
• Who is doing the work
• Reviewers
• Milestones and their expected dates

Writing

At some point, you need to start writing. Investing time upfront in planning greatly reduces the time required for actual writing. You need to:

• Create an outline of the topic
• Create placeholders to fill in details you don’t currently have

When working on a project, be honest about what you don’t know. Ask for help where you need it.

Writing an outline

Outlining is a method of organizing high-level headings, topics, and subtopics. Expect to provide help that answers the following questions:

• Introduction: Why am I using this product, and what do I do with it?
• Requirements and prerequisites
• Getting started: What is the first thing I should do to begin?
• Procedures: What should I do next?
• Additional info: What are the more advanced features of this product, and How can I learn more about this?

Ensure each topic is concise and relevant, and remove unnecessary information.

Review

Reviews can offer valuable insights. You may realize that you left out essential details or left in some author comments. It’s crucial to designate someone to approve the documentation early on.

Remember, feedback on the document isn’t a reflection of you personally or your writing skills. Avoid taking it personally when reviewers analyze a document you’ve worked hard on. You want them to analyze it thoroughly and offer suggestions for improvement.

Treat your reviewers like your most important customers to respond better to your review requests. You need to:

• Send each reviewer the smallest chunk of documentation you can, and don’t make them look at sections that they have already read
• Communicate your expectations to the reviewers and highlight any specific areas you need them to focus on or disregard
• Specify when you need the review comments back, as providing a clear deadline helps ensure timely feedback

Rewrite

With each review, you’ll uncover areas that require revision, cleanup, or enhancement.

• Address errors, typos, and formatting issues in your documentation.
• Ensure clarity by presenting information in an easy-to-understand and accessible manner.
• Enhance your documentation by incorporating missing details and restructuring where necessary.

Style guide

Style guides play a crucial role in technical writing. They establish consistent practices, covering everything from capitalizing titles to formatting numbers. These guides promote uniformity and clarity throughout the documentation.

A well-crafted style guide should answer nearly all writing-related inquiries. A style guide allows writers to minimize the need for frequent clarifications. A comprehensive style guide should cover the following areas:

• Abbreviations and acronyms
• Lists formatting (e.g., bullet points)
• Capitalization rules
  • Some companies use sentence case for their heading
• Handling of numbers (spelled-out and numeric)
• Product naming conventions
• Punctuation guidelines
• Terminology consistency and spelling
• Handling of warnings, cautions, and notes

Mandatory adherence to style standards streamlines peer editing and reduces potential personal conflicts. These resources can serve as backups to the department’s style guide:

• Microsoft Writing Style Guide
• Apple Publications Style Guide

The following are best practices every technical writer should know:

• Use active voice
• Use bullet lists to emphasize points
• Use clear and short words and phrases
• Be consistent in your terminology
• Use gender-neutral language
• Avoid negatives
• Use real use case examples

Writer’s block

Whether you’re a seasoned professional or starting your writing journey, encountering writer’s block is not uncommon. Some tips to help you tackle writer’s block:

• Allocate dedicated time: Focus solely on the task at hand.
• Embrace imperfection. Don’t let the fear of inaccuracies hold you back. Start by writing about how you understand the topic, even if it might be incorrect.

Accept that perfectionism isn’t always attainable. Instead, focus on quality based on four factors:

• Accuracy: Ensure all information is accurate and clearly described.
• Completeness: Expect user needs and include all relevant information.
• Professionalism: Eliminate typos and sentence fragments and maintain consistent formatting.
• Usability: Organize content effectively and present it in a format suitable

Additional information

For more information about how to get started with technical writing, refer:

• Tech writing course by Google
• Docs as Ecosystem book by Alejandra Quetzalli(my GSoD mentor)

I made a presentation a few months back while preparing for a talk about technical writing to a tech community.