How to write excellent technical documentation

As a software engineering manager, you have many plates to keep spinning. Some may be issues you hadn’t even considered before managing a team.

Technical documentation often tops this list. Good technical documentation is a critical driver of a good developer experience with software, both externally facing software like APIs and internally facing platform systems such as CI/CD pipelines and other internal developer tools.

Engineers often neglect technical documentation in the rush to release a product. In this article, we’ll discuss how to avoid this trap and offer advice on creating excellent technical documentation as a regular part of software development.

The benefits of solid technical documentation

Good technical documentation provides many benefits:

• Improves developer experience. Clear and concise documentation with code examples helps developers understand how an endpoint or method call works.
• Reduces support costs. If docs are unclear, developers often feel forced to contact technical support to implement basic functionality. Good docs enable developers to self-service answers to their questions.
• Reduces onboarding time for internal developers. Without docs, knowledge of internal developer processes remains locked in the heads of a few key employees. Docs externalize this knowledge, reducingnew employees’ time hunting down information.
• Fosters better cooperation. Technical documentation explicitly makes assumptions between teams. It serves as a clear reference point that clarifies communication and results in smoother cooperation.
• Ensures consistency. Documentation enables you to surface best practices in coding standards and testing practices, leading to higher code quality and system reliability.
• Simplifies maintenance. Documenting the work done helps others quickly jump in and debug an issue when something goes wrong. This continuity ensures the project’s sustainability over time, mainly as team members come and go.

The challenges with technical documentation

Despite the benefits, some challenges get in the way of delivering good technical documentation with every release. Here are some of the typical ones, along with ways to address them:

Technical documentation takes time to produce

Sadly, good tech docs don’t fall from the sky. Someone has to take the time to write them. Many developers feel (rightly or wrongly) that they don’t have the time to write docs themselves.

Some teams will hire a technical writer—or even build a technical writing team—to address this challenge. However, technical writers will still need to leverage their developers as subject matter experts to ensure the accuracy of the final product.

Solution: Measure how long it takes SMEs to review technical writers’ work and factor that time into each release. Build documentation reviews into your normal review processes, e.g., by including preview builds of docs with each pull request.

Writing technical documents demands specialized skills

Some developers are also great communicators, but not all are. Technical writing is its own discipline that requires not only good communication and writing skills but also an ability to understand one’s audience and present information logically.

Solution: Bring a technical writer to help - or borrow one from another team.

Documentation goes out of date

It’d be great if tech docs stayed accurate forever. But time makes fools of us all. As your products and processes change, the steps and screenshots in your docs will become outdated and inaccurate.

Solution: During each sprint, involve technical writers to assess the impact of changes on documentation. Allocate time to update docs in the release.

Releasing technical documentation requires specific tools

You need to update your documentation for every release. This requires tools to build documents from sources and publish them on your external website or internal API catalog developer portal.

Solution: Select your tools for technical documentation publishing beforehand and build them into your CI/CD process.

Types of technical documentation

Your projects may require several distinct types of documentation. These doc types will also influence your tooling to maintain and publish technical documentation. Each also presents its own unique set of challenges.

Tutorial

Tutorial content shows developers how to use your technology end-to-end to solve a business problem—e.g., a “getting started” guide. These are ideally based on your product’s core use cases. A good tutorial leaves a developer feeling like they have a basic grasp on how to use the technology and how it interacts with other components of their technology stack.

Challenges: While tutorials should be realistic, this is sometimes hard to accomplish without making them overly complicated or specific. Tutorials also need constant revision as your product and processes evolve.

Conceptual

Conceptual documentation introduces your audience to the basic concepts underlying your technology, especially terms specific to the product. For example, documentation for a CI/CD build system might introduce concepts such as source control repositories, branches, environments, stacks, etc.

Challenges: Presenting concepts in a way that gives developers the “big picture” without being too nebulous or confusing.

Application Programming Interface (API )

API documentation describes all endpoints developers can call to integrate your product into their systems.

Challenges: You may have dozens or hundreds of API calls - and need more time to document them all equally. Deciding which API calls are the most important requires in-depth knowledge of your audience and their use cases. You may also need to maintain multiple versions of your API docs whenever your API introduces breaking changes, as consumers will need time to transition between versions.

Blog & support content

Blog & support documentation typically consists of articles that target a specific challenge with your product or an advanced use case. They show the “product in action” and how it solves real-world business challenges. For example, a blog post may discuss integrating your product with a popular third-party Software as a Service (SaaS) application.

Challenges: Typically, experts with deep technical knowledge of your product, such as team engineers, support engineers, and developer advocates, write this content. These team members are usually busy and may need help finding time to write and maintain this valuable content. They may also need support from a technical writer or editor to communicate their message.

How to write technical documentation

Writing good technical documentation requires thoughtfulness and planning. Follow these steps to lay the foundation for a successful tech docs effort.

Understand your audience

Identify the audience: Different audiences will require different levels of documentation. For example, there’s a massive difference between writing for developers, administrators, and end-users.

Assess knowledge levels: You also need to be clear about your assumptions regarding your audience and their existing level of knowledge. Suppose you’re writing documents for developers. Are you only targeting senior, seasoned developers within your technology space? Or do you also need to have documents for less experienced developers that go into greater depth on foundational concepts?

Determine needs and goals: What is your audience trying to achieve with your product? What docs can you create that will address these needs?

Plan your content

• Define the purpose: Define what documents you need of each type - API docs, conceptual docs, tutorials, troubleshooting, etc.
• Organize information. Decide on the presentation format of your information to ensure a logical flow within your documentation. A successful structure often starts with tutorials and getting-started guides, progresses to conceptual documentation and in-depth tutorials, and concludes with reference materials, such as API documentation.
• Choose the right tools. How will you author and publish content? The tools you select will be driven partly by the content you need to publish. For example, writers often write API docs in OpenAPI format as part of the API specification.

Write effective content

Set standards for your team for authoring so that everyone is writing in roundly the same style. Industry best practices include:

• Write clearly and concisely: Use simple language and short sentences. Keep paragraphs short so as not to overwhelm readers with a wall of text. Use active over passive voice.
• Be consistent: Use terminology consistently and maintain the same tone and format. Beware of inconsistencies such as switching voice (1st vs. 2nd vs. 3rd person) throughout the piece. Use the same styles for similar entities - e.g., Courier font for code, bold for UI elements, etc.)
• Use examples: Include practical examples and working code snippets wherever possible.
• Use visuals: Incorporate screenshots, architectural diagrams, flow diagrams, and other visual aids wherever possible. These aid comprehension and break up the monotony of text-heavy content.

Review and test

• Perform a technical review. Ensure that every piece of technical content is reviewed by an SME. If you have a technical writing team, you may ask writers to buddy-read each other’s work.
• Submit documents to usability testing. Ask a portion of your target audience to test your documents and give you feedback. Ask them to tell you what worked, what didn’t, and where your documents could be clearer or more concise.
• Improve iteratively. Update your content based on feedback from your audience. Address product issues as they arise to enhance the overall quality of your product. For instance, consider whether improving the product’s UI could solve common issues users encounter with a task.

Maintain & update

• Use version control. Use file formats (e.g., Markdown files or OpenAPI-style specs stored in Git) that you can keep under source control to track changes.
• Add feedback mechanisms. Build a way into your docs for readers to evaluate their usefulness (e.g., a star system, thumbs up/down), provide feedback, and file documentation bugs.
• Perform regular reviews. Make sure your documents undergo regular reviews to keep them fresh. Track readership metrics to ensure you regularly review and refresh your most-used docs pages.

Ensure accessibility and inclusion

• Use accessible formats. Your documentation should be accessible to people with disabilities, and you should use formats and HTML tagging styles that do this. For a complete list of do’s and do n’ts, refer to Google’s guidelines for accessible documentation.
• Use inclusive language. Avoid ableist language. Use language that is inclusive and free from bias.

Technical documentation for platform engineering

Platform engineering optimizes a company’s development processes to improve developer experience and reduce the time needed to ship software. A platform engineering team improves overall productivity across development teams by defining a common toolset and standards for software development.

Documentation is a central part of platform engineering. It’s essential for documenting standards, processes, and tools used company-wide. Good internal developer documentation reduces cognitive load, which improves developer productivity.

Types of technical documentation used by platform engineering

• System architecture documentation: Diagrams of systems that support developers, such as architectural deployment tiers, internal telemetry systems, supporting services, and communication flows.
• API documentation: Docs on key internal API services shared across multiple teams, such as authentication and metrics. Includes endpoints, usage notes, and examples.
• Configuration management documentation: Guides and reference documentation for configuring a new service or changing an existing service. This configuration can include Infrastructure as Code (IaC) setups, environment variables for supporting services, and other configurations required to support a service in production.
• Operational runbooks: Service teams’ documentation outlining incident response procedures and troubleshooting steps for common service-related incidents.
• Development guidelines: Best practices, coding standards, and tools instructions for internal developers.

How to integrate technical documentation into your development process

The key is to make technical documentation a part of every step of the software development lifecycle—from planning to maintenance. Here are some best practices to get you started.

Make technical documentation part of each sprint

Set aside time not just for writing technical documentation but also for reviewing and testing it. Develop a culture that views documentation not as an extra or nice-to-have but as an integral part of shipping every release.

Define your core technical documentation priorities

Define what documentation you consider foundational to your product for every documentation category. For tutorial content, this would be walkthroughs covering your product’s critical scenarios.

Figuring this out may be more complicated for complex documents like API documentation, especially if you have a large API surface area. One approach is to evaluate how often each API is used (telemetry can help here) and assign “completion rankings” based on the level of documentation each API call should receive.

You’ll want to supply full docs for your top-used APIs, including parameter definitions, descriptions, error descriptions, and complete code samples. For lesser-used APIs, parameter definitions and a simple description may suffice.

Bake technical documentation into your development pipeline

Select authoring tools that enable building a preview of the docs with each code check-in. Bonus points if your tooling can include links to the preview doc build as part of your pull requests.

Where possible, generate documentation from code artifacts. OpenAPI specifications are an excellent example of this, as they enable both defining the API for consumers and including detailed descriptions and usage examples for each endpoint.

Evaluate tools for creating technical documentation

When in doubt, defer to tools that use simple, human-readable storage formats. Markdown is an increasingly popular choice for documentation, as it’s become ubiquitous in the tech world. Markdown files are text files, which means you can check them into Git and diff changes quickly.

Picking good, easy-to-use documentation tools lowers the barrier to creating and maintainingdocuments. Rather than building something yourself from scratch, leverage existing documentation build systems such as GitBook, Confluence, ReadTheDocs, or Sphinx. The tool you select should support automated document generation, collaboration tooling (e.g., change reviews), and version control.

Make time for technical reviews

Your teams should regard documentation reviews as important as any other technical review. Plan document reviews into each sprint, representing them as tasks with a realistic estimated duration.

Encourage your teams to adopt a culture of continuous improvement in documentation. In particular, in platform engineering teams, continuous revision of documents should be an integral part of the job role.

Embed technical writers with your team

A dedicated technical writer can be a great asset. They can focus on creating quality docs while your engineers focus on the product.

A technical writer should have a solid technical background and excellent written communication skills. Ideally, they have several years of experience creating tech documents and can, with time, serve as product SMEs in their own right.

If you hire a technical writer, embed them within your team. You should include them in key meetings, such as sprint meetings and other Agile ceremonies, so they have full knowledge of the product and can track upcoming changes.

Better developer experience through technical documentation

Good technical documentation is a linchpin in enhancing the developer experience. It acts as both a guide and a troubleshooter for those navigating new or complex software.

Well-structured and comprehensive documentation serves as a roadmap, enabling developers to understand the software’s architecture, features, and functionalities without the need to dive into the codebase directly. This clarity accelerates the learning process, reduces integration times, and fosters a more intuitive interaction with the technology.

Moreover, it empowers developers to use platforms to their full potential, encouraging innovation and creativity by providing clear examples, best practices, and detailed explanations of the software’s capabilities.

Beyond mere utility, excellent technical documentation cultivates a supportive community around the software. It becomes a platform for software collaboration and knowledge sharing, where developers can find not only answers to their questions but also insights into solving complex problems.

Furthermore, good documentation can significantly reduce frustration and wait times by minimizing the need for direct support, leading to a more positive overall developer experience. Investing in high-quality technical documentation is not just about making information available; it’s about fostering an environment where developers feel supported, valued, and inspired to explore and innovate.