Technical Documentation - How Can I Write Them Better and Why Should I Care?

Good documentation isn't a chore. It's the key to faster incident response, fewer interruptions, and uninterrupted vacations.

#1about 3 minutes

Why anyone can and should write technical documents

Technical documentation is crucial for knowledge sharing and solving production incidents, where clear information is more important than perfect English.

#2about 2 minutes

Identifying what to document in your daily work

Documentation can be applied to various areas, including system designs, runbooks, code readmes, onboarding guides, and even Slack messages.

#3about 1 minute

Why self-documenting code is a common misconception

Code alone cannot convey the full context, such as the original intent or the reasoning behind specific implementation choices.

#4about 3 minutes

How documentation reduces workload and improves velocity

Writing documentation reduces repetitive questions, enables team self-service, increases development velocity, and helps resolve production incidents faster.

#5about 4 minutes

Using documentation to advance your engineering career

Sharing knowledge through documentation helps you avoid being a bottleneck, increases your visibility, and demonstrates team leadership qualities to management.

#6about 4 minutes

Tailoring content for internal and external audiences

Internal documentation should focus on pain points and non-obvious decisions, while external documentation needs use cases, quick starts, and examples.

#7about 4 minutes

How to structure documents for effective scanning

Structure documents with tables of content, highlights, and links to support the user flow of scanning for information rather than reading word-for-word.

#8about 2 minutes

Using docs-as-code to keep documentation up to date

Docs-as-code integrates documentation into the development toolchain using markdown, pull requests, and CI/CD to prevent it from becoming stale.

#9about 2 minutes

Distinguishing between concept guides and task-based tutorials

Separate "concept" documents that explain the 'why' from "task" documents that provide 'how-to' instructions to get users back to their work faster.

#10about 3 minutes

How to build a team culture of writing documentation

Foster a documentation culture by incorporating it into the "definition of done" for tasks, ensuring it becomes an integral part of the development process.

#11about 4 minutes