How to Create Technical Documentation in 2024 - A simple guide

What is technical documentation?

Technical documentation describes what a product can do. It's mainly created by software development and product teams and helps different parts of a company support the product.

Technical documentation is a broad term. It refers to everything from your first PRD to your API docs for other makers. Let’s define it a bit more.

Different types of Technical Documentation - what’s included v/s what’s not

10 common types of documents that are considered as technical documentation, are:

1. User Manuals

These are booklets or online guides that show you how to use something, like a camera or software. They're full of step-by-step directions.

• Who uses it: Anyone trying to figure out how to use a product
• When it’s made: After the product is made but before it's sold

2. API Documentation

These documents explain how computer programs can talk to each other. If you're building an app, this tells you how to connect it with other software.

• Who uses it: Programmers and app developers
• When it’s made: While the tool for programmers is being made or right after it's finished

3. System Administrators’ Manuals

This is a handbook for the tech pros who set up, fix, and make sure computer systems run smoothly.

• Who uses it: Tech support and IT folks
• When it’s made: After the computer system is ready to go

4. Installation Guides

These guides give you the steps to get a piece of software or hardware up and running.

• Who uses it: Anyone setting up new tech, from everyday users to IT staff
• When it’s made: After making the product but before it hits the market

5. Troubleshooting Guides

Got a problem with your tech? These guides help figure out what's wrong and how to fix it.

• Who uses it: Users having trouble, help desks, IT pros
• When it’s made: After the product is out, with updates when new problems pop up

6. White Papers

Think of these as deep dives into a specific tech topic, offering solutions to tech challenges or explaining how a product can help.

• Who uses it: Decision-makers and experts looking for detailed info
• When it’s made: Anytime, often to explain the benefits of a product or technology

7. Release Notes

When software gets an update, release notes tell you what's new, what's better, and what issues are still around.

• Who uses it: Anyone using the software
• When it’s made: Along with software updates

8. Product documentation

You will need a lot of writing to streamline your product development. And all your project plans are a part of technical documentation. This detailed list tells you exactly what a product can do and its features.

• Who uses it: Product managers and other team members usually champion this.
• When it’s made: At the start of making a product

9. FAQs (Frequently Asked Questions)

Here you'll find answers to common questions about using a product or service.

• Who uses it: Customer support teams and users looking for quick answers
• When it’s made: Starts with most commonly asked questions in demo/discovery calls. It’s expanded by adding most likely questions that other people will ask. FAQs are highly volatile based on your ICP, their journey milestones, etc.

These start small and evolve with time, as most user documentation does. As your product and ICP evolves, its FAQs will change. Technical writers usually are the ones that take this up.

10. Developer Guides

These guides are for the coders, giving them the nitty-gritty on how to use a technology or work with a programming tool.

• Who uses it: Coders and software builders
• When it’s made: While creating the tech and updated as it changes

So, who uses technical documentation?

Technical documentation is used by internal devs, IT staff, CXOs, PMs, CS teams, end-users, and external devs.

And, what’s NOT Technical Documentation?

Sometimes people get mixed up and think some documents are technical guides when they're really not. While some of it - like your HR handbook - is obviously non-technical documentation, some documents fall in a grey area. Here's a quick look:

• Marketing Materials: Stuff like brochures and websites that might use tech talk but are really trying to get you to buy something. They're not for teaching you how to use or fix the product.
• Business Plans and Reports: These papers talk about the tech side of a business or new product ideas but are mostly about making plans, guessing future money, and checking out the market.
• Internal Policies and Procedures: Important for running a company, but they're more about rules, doing things right, and what employees should do, not about how to use tech stuff.
• Technical Proposals: They suggest new tech projects or solutions, talking about the good stuff that can come from it, if it's possible, and how much it might cost, instead of step-by-step guides.
• User Stories and Use Cases: Used a lot when making software to explain what a feature should do from a user's point of view. They help figure out what users need but aren't detailed tech instructions. Don’t get us wrong, user stories and use cases help teams decide on what to build next. But, it still counts market research, not technical documentation.

Summarising, here’s a nifty list on what is technical documentation and what isn’t:

‍

How to create Technical Documentation

Step 0: Put down your technical writing style guide

Your technical writing style guide will help all contributors keep a consistent tone and vision for writing. The best example is the Apple Style Guide. The beloved brand works hard to keep a similar style of writing everywhere.

And so should you.

While it may not matter right now, it will matter months from now when your team and user base scales up. This includes defining fonts, to step-by-step instructions for document creation, and workflow details.

Step 1: Figure out what you need right now

You don’t need all 10 types of documentation right off the bat. Different needs evolve and come up across your development lifecycle:

1. Day 0 to Day 30: Ideation stage

• Product Specifications: Start with the core idea of your product. Outline features, capabilities, and user needs.

2. Month 1 to Month 6: Development stage

• API Documentation: If your product includes APIs, start drafting the documentation as development progresses.
• Developer Guides: Begin work on guides if your product is aimed at developers, updating as features are finalised.
• Technical Proposals: Continue refining these documents if adjustments are needed based on stakeholder feedback or evolving project scope.

3. Month 7 to 12: Launch prep stage

• System Administrators’ Manuals: Start drafting as the system's architecture is solidified.
• Installation Guides: Draft these guides once the installation process is defined.
• User Manuals and Troubleshooting Guides: Outline and draft user guides based on the developed features and anticipated common issues.
• FAQs (Frequently Asked Questions): Compile questions based on beta testing or anticipated user inquiries.
• Release Notes: Prepare for the initial launch, detailing features, bug fixes, and known issues.

4. Month 13 to 24: Post-Launch and Growth stage

• Update all previous documentation: Reflect changes, updates, and feedback from real-world use.
• Continuous Updates:

• Product Specifications: Update as new features are added or significant product changes occur.
• API Documentation and Developer Guides: Keep these documents current to encourage developer engagement and ease of use.
• System Administrators’ Manuals and Installation Guides: Revise based on software updates or changes in system requirements.
• User Manuals and Troubleshooting Guides: Regularly update these documents to incorporate new solutions and address additional user questions.
• FAQs: Continually add new questions as users interact more with the product.
• Release Notes: With each new version or update, provide detailed release notes to inform users of changes.

As you can see, if you’ve just started building your product, you might just have different iterations of your PRD. However, if you’ve launched already and are in the growth stage, you will most likely already have created all types of different technical documentation by now but it may be scattered.

Based on this, start a new workspace in Slite, and create different channels/pages for only the type of documentation you have/need. In case you’re looking for our template, directly copy it to your Slite workspace here.

Step 2: Collect your existing docs in one place.

Once you’ve structured your homebase, you will have a clear picture on all the documentation you should have at this stage.

Since you might have some of it already, start importing from other sources. Rather than staring at a blank page, start importing the documentation you already have. Right now, this may be loose meeting notes, product roadmap, or PRDs from your brainstorming calls. Usually, this type of documentation is created in meetings as quickly created ad-hoc Google docs, Miro boards, Figjam boards, etc.

Most knowledge base tools let you import docs from Google Docs, Notion, or any other popular knowledge base you’re using right now. Once imported, start organising them across categories and name them properly. If your knowledge base software has a verification status feature like Slite, use it to verify the stuff like technical specs, dev guidelines, etc.

Step 3: Start writing the docs that don’t exist yet, but should.

By step three, it’s time to get started with the actual content creation process. Knowledge creation is never a one-person job. It’s a collaborative process and that’s why you should start involving your team at this stage.

This has 2 benefits:

1. It’ll get done faster if everyone contributes by sticking to their timelines.
2. It kickstarts the culture of documentation in your team

The best technical documentation is usually produced when:

1. Every document has an owner and contributors
2. Writers are thoroughly briefed on what to write
3. Writers use simple language, headings, and a lot of images to make their documentation extremely readable.
4. Writers know who all will be reading the document
5. Every completed document is reviewed at least once by someone else.
6. Most documents are allotted a verification status so your team knows which documentation is relevant, and when they need to update it.

This will ensure that the content is not only clear, well written, and grammatically correct, but also that it will be effective for users.

If your technical documentation includes any how-to guides or steps to follow, make sure your team members actually test out those steps and confirm that they accomplish what they’re supposed to accomplish.

Step 4: Review the readability of your docs

Since devs, PMs, and other technical folks write your technical documentation, it’s important to double-check it for simplicity. If your documentation can’t be understood by other stakeholders, it’s worthless to have.

This is why, ensure that your documentation:

• Has images, videos, etc. to break down complex SOPs/how-to’s (if any)
• Has internal links to related/relevant articles
• Is broken down by multiple subheadings
• Uses extremely simple language
• Is skimmable (people prefer to skim content, not read chunks of paragraphs word-to-word)

It’s important to put it through a testing phase and check for organisational issues, confusing information, and usability problems.

In order to accomplish this step, you can also look for external users to test out your documentation. Have them read through it, use it to help them in completing the tasks it’s supposed to, and provide you with their honest feedback. It’s important to ensure that your testers are external because they will be looking at your documentation with a fresh pair of eyes and won’t have any bias that will affect their evaluation.

Step 5: Ship, collect feedback, iterate.

You know this product philosophy. You just gotta apply it to your documentation too.

Once you’ve published your technical documentation, promote it and proactively ask users for feedback.

Secondly, put down maintenance and hygiene protocols for your documentation. Technical documents are dynamic and go through updates and changes in accordance with the products they cover. As such, it’s a good idea to establish a protocol that details what needs to be done when new information needs to be added, changes need to be integrated or general maintenance needs to be made.

Many companies choose to implement a maintenance schedule for their documentation. They set specific dates where they evaluate whether any changes need to be made, so all their information is always up to date and modifications never get overlooked.

Examples/Inspiration of the best technical documentation

Here’s 7 good examples of developer documentation loved by internal and external stakeholder alike:

Example 1: Stripe - The Benchmark for API Documentation

What's Good

• Sticky Sidebar for Navigation: Stripe's documentation features a sticky sidebar/table of contents, greatly enhancing user navigation by providing easy access to different sections without scrolling. The sidebar structures all their documentation like a textbook would. So you can jump from any document to another just via the navbar.
• Sticky Interactive Sandbox: The preview/live sandbox code section allows developers to write, test, and view code in real-time, making it an invaluable tool for learning and experimentation.
• Code Copying Feature: This functionality enables users to easily copy code snippets for use in their projects, streamlining the development process.

What's Bad

• Nothing, really. Stripe’s documentation does everything right. It’s simple to read, the code is easy to copy for devs, and the UI is very intuitive.

The clear, concise, and interactive nature of Stripe's documentation has made it the go-to favourite integration among developers, particularly when compared to PayPal’s software documentation.

Example 2: MDN Web Docs - An extremely close runner-up

What's Good

• AI Help: It’s the only technical documentation example in this list that has added AI for technical documentation search. It provides MDN-sourced answers complete with consulted links, making information retrieval efficient and effective.
• Comprehensive Content: Offers an exhaustive range of topics, making it more comprehensive than many of its competitors. It has docs created by their internal teams, subject matter experts, technical writers, etc.
• Dedicated Playground: Allows users to experiment with code directly within the documentation, enhancing the learning experience.

What's Bad

• Despite its comprehensive coverage, MDN lacks a singular master URL for easy jumping across different sections, which some users find inconvenient.

However, it’s worth noting that their AI Help feature more than makes up for the lack of master navigation.

Example 3: Twilio - The closest to Stripe, and the best at process documentation

What's Good

• Interactive Sandbox: Like Stripe, Twilio offers a sandbox for live code previews, enhancing hands-on learning.
• Page Rating Option: Users can rate documentation pages, offering direct feedback to improve the resources.

What's Bad

• Navigation Challenges: Some users find it slower to navigate through the documentation, possibly due to its comprehensive nature.

Twilio's documentation is extremely detailed and is most comparable to Stripe in terms of user experience. Though, some devs do find Stripe's layout cleaner and easier to navigate.

Example 4: Django - Gets the job done

What's Good

• Extensive Coverage: Django's documentation covers everything from the basics for beginners to advanced topics for experienced developers, making it a one-stop-shop for Django users.
• Well-Organized: The documentation is logically organised, making it easy for developers to find the specific information they need.

What's Bad

• Due to its comprehensiveness, new users might find it daunting to navigate through the vast amount of information available.

Key Thing to Note

• Django's documentation is a gold standard for framework documentation, offering detailed guides and tutorials that are crucial for both novice and seasoned developers.

Example 5: Laravel - Minimal but comprehensive

What's Good

• Minimalistic Navigation: A minimal sticky sidebar simplifies navigation, making it easy for users to find what they need without distraction.
• Dark Mode Toggle: The option to switch between light and dark modes caters to different user preferences, enhancing readability.

What's Bad

• While its simplicity is a strength, some users might seek more interactive elements similar to those found in Stripe or Twilio's documentation.

Laravel's documentation primarily stands out for its simplicity and effectiveness, especially in how it uses tables, images, and simple language to convey complex topics.

Example 6: DigitalOcean - Redefines the meaning of comprehensive

What's Good

• Community Engagement: Features like a comment section at the end of tutorials foster a strong sense of community.
• One-Click Copy Buttons: Enhances usability by allowing users to easily copy code snippets.
• They have an article for everything: They’ve covered all their bases to even the smallest of use cases.

What's Bad

• While comprehensive, some tutorials may assume a level of pre-existing knowledge, potentially making them less accessible to absolute beginners.

DigitalOcean's documentation excels in engaging the community, providing a platform not just for learning but also for discussion and knowledge sharing.

Example 7: Arch Wiki - A familiar layout

What's Good

• Simplicity: Offers a Wikipedia-like simplicity in its design, focusing on delivering information in the most straightforward manner.
• Interlinking: Excellent interlinking between pages aids in navigation and provides a comprehensive web of information.

What's Bad

• The minimalist approach might not cater to users who prefer more guided, tutorial-based documentation with interactive elements.

The Arch Wiki is renowned for its accuracy, up-to-date information, and no-nonsense structure, making it a favourite among users who prefer precision and depth in documentation.

Do’s and don’ts of good documentation

What to Do

1. Make It Easy to Navigate: Use a sidebar or a clear contents page so people can find what they need quickly, just like Stripe does.
2. Add Interactive Examples: Let users try out code or see it in action. Stripe and Twilio are great at this, making learning more fun and hands-on.
3. Keep It Simple and Clear: Write in a way that's easy to understand. Laravel is good at this, turning complex ideas into simple explanations. Technical writing should be accessible to everyone.
4. Let Users Talk to Each Other: Have a place for feedback or discussions. DigitalOcean's tutorials are more helpful because they include user comments and discussions.
5. Cover relevant information: Talk about both simple and complex topics to help both new and experienced users. MDN Web Docs does this well by offering lots of detailed guides on web technologies.
6. Update Often: Always keep your documentation current to ensure users have the latest information. The Arch Wiki is always up to date, which is super helpful.

What to Avoid

1. Don’t Overload Users: Too much information all at once can be overwhelming. It's better to organise content so it's easy to digest.
2. Don’t Skip Examples: Users need examples to understand how things work. Make sure your documentation includes practical, real-life examples. Go the extra mile and add things like screenshots, or screen recordings to your technical content.
3. Don’t Ignore Design: A messy or hard-to-read documentation site can push users away. Make sure your site is tidy and easy to use.
4. Don’t Ignore Feedback: User suggestions can help improve your documentation. Pay attention to what users say.
5. Don’t Assume Everyone Knows Everything: Remember, not everyone will be an expert. Include basic guides for beginners and more in-depth information for those who need it.
6. Don’t Forget Search: A good search function makes it easier for users to find exactly what they need without wasting time.
7. Don’t bombard acronyms: Be mindful of using acronyms. While they speed up the writing process, ensure you put down the full-form of acronyms for those who might not know them.

Final takeaway - Structure like a textbook, have a functional design, and keep improving it.

Remember, the best documentation grows and adapts with its users. It listens to their struggles and triumphs, evolving to meet their needs better. It's not just about having all the answers but about making those answers accessible and engaging for everyone, from the curious beginner to the seasoned expert.

So, take a page from the playbooks of Stripe, MDN, Laravel, and others who lead by example. Aim to create documentation that doesn't just inform but inspires and empowers your users.

Simply put,

Good technical documentation is a selling point of your product.

Great technical documentation means everyone ships faster. That’s why developers internally vouch to use apps for great documentation. Be one of them.