Technical Documentation
What is Technical Documentation?
Documentation is any communicable material that is used to describe, explain or instruct.
Technical documentation is any documentation created to help users or developers understand a piece of product’s features and functions. In theory, all the questions that you might have about the product should be clearly answered.
Why we need Documentation?
You may hear jokes that nobody ever reads documentation, but it exists to help end-users/readers to achieve a goal.
Documentation should be an integral part of any product or process.
The main benefits of documentation:
- Improved quality and process control.
- Easier onboarding and training.
- Reduces knowledge loss.
- Saves time.
- Increased sales.
Types of Technical Documentation
There are certain types of documentation for specific purposes. Let’s cover common of them:
- User Guide (Manual) — goal of such guides is to educate the users.
- Process Documentation — describes the development of a product.
- API (Application Programming Interface) Documentation — describes what services an API offers and how to use those services.
- Release Notes — explains what new things are incorporated, how the new feature works, or what kind of a bug is managed to fix.
- User Requirements Document — specifies what what the users expect from your product or service.
Take a look at 12 Types of Technical Documentation +Examples (2022)
Documentation Best Practices
Before to start writing any documentation it’s better to plan how are you going to do this and start with the draft.
To write an effective technical documentation you need to know the topic and the audience that will use it.
A good technical documentation should be:
- written in simple language (avoid using jargon, terms that reader doesn’t know)
- use visual elements (videos, diagrams, tables and etc.),
- and be readable (use formatting, code blocks) to make it easier to understand.
Remember, visual is always better than plain text. Rule: Show don’t tell.
Document what matters first to make sure that your documentation contains all the necessary information and explains it well for readers to get the most out of your product, but remember to avoid wasteful information.
Make sure that your documentation is consistent. Users should step-by-step see the way how documentation solves their problems. For example if you open any good documentation you will see left sidebar with main content that divided by topics.
The critical thing to keep in mind, is when you have teams and they have to document different projects, processes and etc., all types of documentation should live in one place, to avert the problem of finding all these documents. Choose the best tool that can fit all teams. Don’t spread your documentation over everywhere.
One more important thing it’s how you will keep documentation up to date, no one loves outdated information and this may cause distrust of documentation in the future.
Also check out Technical Writing Courses by Google to learn how to plan and author technical documents.
To learn more about How to make your documentation better:
- How to writing effective documentation.
- How to Write Documentation for People that Don’t Read
- Basics of Technical Writing for Software Documentation
- Documentation for design system
- Technical Writer Guide
- Clear and Concise Technical Writing
- Writing great documentation
- What nobody tells you about documentation
- The Anatomy of a Software Design Document
- Writing effective technical documentation — Online Talk
- Technical Writing Webinar — Technical Documentation Essentials
- How to Write a Technical Document
- Essential Qualities of a Technical Writer with Ellis Pratt of Cherryleaf
- Webinar on How to Create a Successful Knowledge Base
- How to Create Helpful Technical Documentation (+Best Practices)
- Document Lifecycle: Ensuring Your Documentation Efficiency
- Writing Better Documentation for Developers by Meredydd Luff
Tools for Documentation
When it comes to documentation you really have to decide where it should live.
Technical documentation tool helps to create and manage documentation faster and easier. You can use a tool that already exists or implement your own full custom.
Key features of any documentation tool:
- Easy to use. For a good documentation tool not enough just provide content, users should be happy to use it.
- Accessible. The right tool should allow users to share and get access to documentation within one click.
- Resources support. Some documentations contain not only text but also hyperlinks, images, videos and etc. it’s really important to know that tool can handle this well.
- Collaboration. Collaboration makes documentation easier to maintain and get feedback from users.
There are a lot of tools that can be used to manage your Documentation, here are just some popular solutions, and each have own pros and cons: Confluence, GitHub, Dropbox Paper, Notion.
To learn more about how to use documentation tools:
- Develop Technical Documentation in Confluence
- How GitHub uses GitHub to document GitHub
- GitHub is your documentation landing page
- Writing on GitHub
- Read the Docs: simplified software documentation, automatic building, versioning and hosting of docs
Docs as Code
Docs as Code is a practice of using the same tools and workflows as your code. This means create, manage and publish documentation similar to application.
The goal is to empower engineers to write technical documentation frequently and keep it up to date by integrating with their tools and processes.
To learn more about Docs as Code:
- Docs as Code: Write for Developers as a Developer
- How we are solving internal technical documentation at Spotify
- Docs as Code
- Use Gitlab to Deliver “Docs-as-Code” Technical Documentation
- Working in public — our docs-as-code approach
- Marcia Riefer Johnston & Dave May — One AWS team’s move to docs as code
- Create beautiful and localized documentations and websites using MkDocs + Github
- Building Docs like Code: Continuous Integration for Documentation
