How to create great technical documentation: ultimate guide - The first knowledge sharing application in Vietnam

What is technical documentation?

Technical documentation is content that explains how a product works. This includes product methods, features and functions.

Documentation can be external or customer facing—helping the users of a product, or developers working with it, understand how it works. It can also be internal—primarily intended to share knowledge about a product or system within an organization so that other developers can contribute to or help maintain it.

Traditionally, technical articles were created by technical writers in collaboration with subject matter experts (SMEs) who have in-depth knowledge of the specific subject matter covered. In modern DevOps organizations, increasingly it is SMEs themselves, including developers, who are responsible for creating technical documentation.

Importance of technical documentation

Importance of external technical documentation for customers

Good documentation provides a complete, accurate, and easy to understand picture of the software, its architecture and components, and its functionality. It explains how everything works and documents the rationale behind important parts of the system.

When customers use the software, they may access technical documentation along to assist them in getting started with the product, learning its basic functionality, or exploring advanced features. Documentation can typically be viewed within the application, eliminating the need for customers to switch context when asking questions, and improving user experience.

Having strong technical documentation has additional benefits:

Makes it easier to market a product to potential customers, because it describes software features in more detail than typical marketing literature.
Provides answers when customers have technical questions, reducing the load on technical support staff.
Allowing teams to gain a deep understanding of the existing product portfolio, supporting future product development roadmaps.

Importance of internal technical documentation for DevOps team

DevOps teams use internal documentation to record internal knowledge, such as best practices, processes and procedures, and software specs. It provides a reference for team members, employees, and other parties can reference internal documentation to complete tasks and standardize work across the organization.

Unlike external documentation created for customers and users, internal documentation is for employees and partners. DevOps teams typically host internal documentation in a private knowledge base accessible only to authorized users with credentials.

Here are the main benefits of internal documentation:

Clear communication and knowledge sharing—internal documentation can significantly improve team communication. DevOps teams often use it to facilitate asynchronous communication, making internal documentation accessible at all times.
Faster onboarding experience—new employees can use internal documentation to quickly get familiarized with policies and expectations. When the information is available through one centralized location, new employees can spend less time looking for information or asking their colleagues to clarify subjects.
Improved productivity—internal documentation provides clear information, often accessible through search queries and logical categories. As a result, employees can quickly find the information they need to complete their jobs.
Avoiding technical mistakes—DevOps teams can use internal documentation to provide product specifications and information about the development process. Team members and other parties can use this information to work more accurately and make fewer technical errors.

Internal documentation ensures all parties collaborating on a project can quickly learn about technical matters without asking an engineer. It can also protect against liabilities that might result from defects in products.

Types of technical documentation

Process documentation

Process documentation describes product development. It might cover one or more phases of the development life cycle—from design through to development, testing, deployment, and ongoing operations.

For example, process documentation could include project plans that provide timeline, milestones, and budget at the start of a development project. Or it might provide detailed step-by-step procedures performed as part of the development lifecycle, such as testing or deployment procedures.

Examples of deliverables:

Plans and estimates—created at project start and updated to reflect ongoing projects.
Reports and metrics—generated periodically to analyze how an organization is optimizing time and resources.
Working documents—documenting solutions created during project implementation, including code, architectures, and ways to solve technical problems.
Standards—coding practices, naming and versioning conventions, user experience design, and other standards that specify how a product should be built, presented, or structured.

User documentation

User documentation, also known as product-based documentation, provides information about a finished product, which might be used either by customers or internal staff. Documentation may tell you how to install, use, or troubleshoot a product. It commonly explains product features, provides detailed procedures for using them, and answers frequently asked questions.

User documentation is typically shipped with a software product, and also delivered online in the form of a documentation website or knowledge center.

The audience of user documentation might be an end user, but in other cases documentation is aimed at experts such as developers, engineers, or technicians. A common example is application programming interface (API) documentation, which tells developers how they can access a product remotely using API commands.

Examples of deliverables:

Quick start guide—an overview of product features and a basic usage guide.
User’s manual—complete information and instructions on installing and using the product from an end-user’s perspective.
Administrator’s manual—detailed information for an administrator responsible for setting up and managing a system in their organization.
API documentation—explanation of a software solution delivered via API, how to integrate with it, and details of the commands and functions it provides for an API user.

Learn more in our detailed guide to types of technical documentation (coming soon).

5 great technical documentation examples

The best way to learn how to create great documentation is to see examples of companies that do it well. Here are five of the best examples of customer-facing online documentation.

Stripe

Stripe is a financial services and SaaS provider that provides online payment solutions and infrastructure.

Stripe’s online documentation portal provides an easy introduction to product information. The portal focuses on audiences with different levels of knowledge and provides the most relevant data for each audience. Although this document favors developers as its primary audience, its concise style also supports readers from other backgrounds.

Notable features of Stripe’s documentation:

It is reader-centric, not marketing-oriented.
The portal presents products in a simple and understandable way. It divides resources into sections and subsections, letting users access each section in any document using the navigation bar.
The information is designed for everyone—not designed only for developers or people with technical backgrounds, but also for business users who want to integrate Stripe’s services into their applications.
Provides search tools for fast, accurate access to information.
Dedicated support catalog, a type of knowledge center with answers to technical questions asked by developers.

Google

Google offers hundreds of products, each with its own documentation. A distinguishing feature of Google product documentation is the combination of static answers with community forums where users can submit feedback and ask questions.

Google also developed a culture of internal documentation. In 2014, after developers within the company experienced productivity issues due to poor or lacking documentation, Google introduced a system called g3docs that made documentation much simpler.

The system provides one simple way to document code, with easy Markdown authoring to let developers stay within the IDE, and automatic rendering into attractive HTML pages. Internal documentation contributions grew significantly to 200K updates per month.

Apple iPhone

Apple’s iPhone is known for its intuitive and easy-to-use features, and aims to provide documentation that is as easy to understand as the device interface.

Notable points from iPhone documentation include:

Clear, beautiful design makes documentation attractive and easy to read.
There is an option to choose the iOS version a user has installed. This helps end-users ensure that the instructions are accurate and relevant to them.
A table of contents on each page allows easy navigation to content sections and device-specific screenshots.
Pages are structured into short, byte-size sections, each with an illustrative screenshot.

Docker

Docker is an open platform for building, running, and deploying containerized applications, which is used by millions of developers. Docker documentation is appreciated by many developers.

Notable features of Docker’s documentation:

Clear phrasing, short sentences, and use of titles to break up content.
Sensible content organization and navigation structure.
Several types of content for different needs—getting started guides, installation instructions, guides for working with Docker, language-specific content, product manuals, and API/CLI reference.
Summary and “cheat sheet” section at the end of each chapter. These sections help reinforce concepts the reader may have missed.
All pages in the documentation are provided with internal links so that users can easily find more details or background on a concept or topic.
A cool feature is the ability to toggle between night and day mode.

Dropbox

Dropbox is a popular cloud storage service, known for its ease of use. It provides the Dropbox Help Center, with information on using the Dropbox application, account and billing issues, and information about how to integrate Dropbox with other systems.

Highlights from other Dropbox documentation include:

Engaging illustrations that help clarify instructions and reinforce the brand voice.
Provides help for specific use cases such as buying or selling content on Dropbox, creating and uploading content, and sharing content.
Documentation broken up into a blog article format, making it easy to share and navigate.
Integrated community section with the ability to ask other Dropbox users for help.

Learn more in our detailed guide to technical documentation example (coming soon).

Technical documentation structure and design

For technical documentation to be useful, it must be readable and accessible. A big part of this is making it structurally logical and easy to navigate. Before you start creating content, you should think about how it will appear to the end user of the documentation. This includes:

Page design—what each technical article looks like, what it contains, and the hierarchy of information.
Navigational structure within an article—the order in which information appears, how users navigate and navigate, links or linked articles.
Navigational structure between articles—how articles are collected into categories or topics, and whether users can easily find relevant information.
Product and version architecture—in most organizations, there are multiple sets of documentation for different products and versions. It must be very clear to the user how to find documentation for the product or version they have.
Search—a key function of modern documentation is the ability to perform natural language search for a topic or function and easily find relevant content.

It is important to keep documentation clear and concise. Whenever possible, avoid long blocks of text and use visual content to make information easier to absorb.

Poor structure results in a negative user experience

When users dislike documentation, it’s usually not because of lack of information, or even because it is not well written—but due to poor structure. This is a phenomenon known as processing fluency—people prefer things that are easier to think about and understand.

Here are a few aspects of documentation that make it difficult for readers to process and creates a poor user experience:

Navigation or user interface is cluttered or unclear
Too many options presented to the reader at the same time
Pages or units in the documentation are very long
Content is presented as continuous text without headings to break up the information
Text is difficult to read due to poor design, layout, or typography

By addressing these issues in documentation, organizations can make it useful and attractive to users. This will increase the chance users will actually read and discover the information they need.

It goes without saying that even the best structure won’t help when documentation is incorrect, out of date, or poorly written. The point is that even if all these elements are in place—the user will not benefit from the documentation unless it is properly structured.

The importance of templates

In most cases, good documentation structures can be replicated and reused, both within the same product documentation, between products, and even across entire industries.

Always try to start a documentation project from a template or schema, which can serve as a blueprint for how data should be structured. Of course, do not take the template as is—consider the reader and adjust it to their specific needs.

For example, it is common to create a template for a technical article. This could include elements like:

Title—clearly describing what the reader will learn.
Table of contents—helping navigate inside the document.
Content sections—specifying how the content should be broken into sections.
Summary—main takeaways from the content.
Related content—links to supporting information.

Having a consistent structure for all articles (and similarly, having a consistent structure for a documentation portal homepage, a main topic page, etc) helps readers orient themselves and creates a clear flow through the content.

Understanding what content matters most

When structuring documentation, a key question to ask is which topics are the most important for users. There are always common problems or commonly asked questions, and other topics that are esoteric and only relevant for some users. By putting the frequently requested content front and center, you can help the average reader derive more value from the documentation.

Improving productivity with technical documentation tools

Technical documentation tools make it easy to document, store, and share technical content. A good tool enables:

Easy authoring of documentation for internal teams, accessible both to professional writers and technical roles.
Delivering documentation in a convenient online format.
Creating content that is easy to read, browse, navigate, and search.
Easily adapting and updating content to reflect changes to software.
Storing and organizing version history of pages and documents.
Controlling sharing and access for authors, readers, and users.
Easily linking related content so users can discover the most relevant content.
Adding rich media such as video and audio to documentation.
Accessibility for mobile devices and offline users.

When choosing a technical documentation tool, consider the following evaluation criteria:

Scalable pricing—technical documentation software solutions are usually sold with per-user, monthly plans that provide limited storage or page views. With a large support team and a large number of views, this can quickly become an issue.
Granular access control—technical documents often have a mix of private and public parts. Therefore, technical documentation software should have access control that can limit access to specific pages, documents, or parts thereof.
Writing and editing experience—authoring documentation is a critical part of the process. If it’s not convenient, employees won’t create documentation or frequently update it.
End user experience—each documentation platform presents documentation in a different way and has a different user interface. Ensure the reader can view documentation in a way that is attractive, professional, and suitable to their context and skills.

Learn more in our detailed guide to technical documentation tools (coming soon)

Best practices for writing winning technical documentation

Consider your audience

Always consider who the article or document is written for:

If it is intended for end users—it should be written in plain language so that the reader can immediately understand it.
If it is intended for stakeholders—it is important to avoid complex jargon, technical jargon, or acronyms that they may not be familiar with.
If it is intended for technical experts—use terminology they are familiar with and give them the technical details they need to do their work. Even then, keep things as simple as possible and present only the information that is absolutely necessary.

Keep technical documentation up to date

Proper maintenance is very important, as outdated or inconsistent content automatically loses its value. If requirements change during software development, you must ensure that there is a systematic process for updating documentation with the new information. It is also important to notify customers when updates to documentation are available, if a product is already released.

It is a good idea to create a documentation maintenance and update plan—and also recognize that documentation updates are a major task that requires time from the entire software development team. The plan can be linked to a development plan, adding items to a sprint or epic to create updated documentation for each release.

Use version control tools to manage the process more efficiently. Track changes, keep previous versions and drafts, and closely coordinate change management to prevent conflicts.

Create a culture of collaboration

Agile development methods demand a collaborative approach to document creation. DevOps teams may or may not have dedicated technical writers:

If writers exist on the team—they cannot operate in a vacuum, and need close cooperation with developers and product owners to understand product features and their value.
If there are no writers—the burden of documentation falls on technical team members. In this case it is critical to give developers the tools and processes to efficiently create documentation while coding new features.