Power Brief On Writing Technical Docs 📑

Ever wondered what the most important skills in software development are? Is it code design? System design? Tests? Naming variables or handling caching?

While all of those matter, one skill that’s often underrated is technical documentation.

Writing any document can be tough, but the return on investment is massive. In this post, we’ll talk about technical docs — their purpose, benefits, and how you can write docs that communicate your ideas clearly. This won’t cover everything (there are professionals whose whole job is writing docs), but it’ll give software engineers a solid foundation.

Benefits

“I write not to tell, but to understand it myself.” — someone

General Benefits: Writing brings clarity and saves time in the long run.
Specific Benefits: Better collaboration, reduced misunderstandings, and long-term value as others (or even you) can refer back to it later.

Content

Often when people write technical docs, they start right with a lot of detail which overwhelms and shuts the reader off. Ideally the content should follow a funnel like structure with broad details first and then getting deep into the technicals of it.

This helps the readers smoothly travel through the context while reading the doc and hence collaborate to suggest something.

Here’s a rough structure to follow when writing a technical doc:

1. Introduction: What is this doc about?
2. Context: Why does this matter? What problem does it solve?
3. Pre-requisites: What do readers need to know before reading further?
4. Deliverables and Constraints: What’s the expected outcome and any limitations?
5. Design (if applicable): Outline the design decisions.
6. Solutions: Briefly describe possible solutions, and list pros/cons in a simple table.

7. Details of Implementation: Keep this section flexible.
8. Monitoring: How will you know if the solution works? What will you track? Using a 3 pronged step usually helps — i) How do you know your change works? ii) How do you know your change made the user successfull? iii) How do you know incase your change breaks?

9. References: Include links or resources that support your doc.

Guidelines

1. Keep it simple.
2. Focus on clarity over complexity.
3. Understand your audience’s level of technical knowledge.
4. Update your docs regularly to stay relevant.

Friction

Docs can face friction points, like being outdated or overly complex. Dealing with these involves:
- Regular updates.
- Keeping content concise and accessible.

Conclusion

Writing technical docs may seem like extra work, but it saves time and effort down the road. If you’d like to see example docs, feel free to ping me!

Technical Documentation Template

# Title

## Introduction
Explain what this document is about.

## Context
Why is this important?

## Pre-requisites
What knowledge is needed before diving into the doc?

## Deliverables and Constraints
What are the expected outcomes? What limitations should be considered?

## Design (Optional)
Include design decisions if relevant.

## Solutions
- Solution 1 (Pros/Cons)
- Solution 2 (Pros/Cons)

## Details of Implementation
Outline the steps to implement the solution.

## Monitoring
How will success be measured?

## References
List any relevant links or documents.

Keep it alive

We know the times keep changing and at the time of making this checklist AI is still getting in little parts to the development process. Keep suggesting the changes as you deem fit based on when you’re reading it