> Markdown version of [/videos/681-technical-documentation-how-can-i-write-them-better-and-why-should-i-care?t=170](https://www.wearedevelopers.com/videos/681-technical-documentation-how-can-i-write-them-better-and-why-should-i-care?t=170). Every page supports `.md` or `Accept: text/markdown`. Links point to the HTML versions so they work for humans too. Agent guide: [/agents.md](https://www.wearedevelopers.com/agents.md).

---

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

Still hoping your code is self-documenting? Discover how adopting Docs-as-Code prevents frustrating midnight incidents, accelerates onboarding, and permanently eliminates single points of failure.

- **Speakers:** Hila Fish
- **Event:** World Congress 2023
- **Published:** September 21, 2023
- **Duration:** 31:23
- **URL:** https://www.wearedevelopers.com/videos/681-technical-documentation-how-can-i-write-them-better-and-why-should-i-care

## Summary

The pervasive developer myth that "code is self-documenting" routinely leaves teams vulnerable during critical production incidents and bogged down by repetitive troubleshooting inquiries. Establishing robust technical documentation transforms this dynamic. Rather than solely being a bureaucratic chore, writing effective runbooks and knowledge bases prevents individual engineers from becoming single points of failure, guards against vacation interruptions, and drastically reduces long-term work volumes by enabling self-service onboarding and confident incident response.

To lower the barrier to entry, engineers do not need to be professional technical writers; they simply need to share knowledge effectively. Because readers interact with documentation by scanning rather than reading word-for-word, formatting matters immensely. Using concise phrasing, simple English, and visual highlights improves readability. Crucially, documentation must strictly separate conceptual background (the architectural "why") from task-based runbooks (the "how-to"). For complex internal systems, documenting friction points, workarounds, and non-standard decisions provides just as much value as providing external-facing API quick-starts.

Implementing a "Docs-as-Code" methodology integrates documentation directly into the development toolchain using Markdown, keeping resources close to the codebase and accessible within the IDE. By incorporating documentation checks into CI/CD pipelines using validation tools, teams can enforce updates during pull requests, preventing artifacts from going stale. Ultimately, transforming documentation from an afterthought into an organizational habit—specifically by mandating it as a non-negotiable part of a ticketing system's "Definition of Done"—fosters a resilient engineering culture that drives continuous learning and clear business alignment.

**Keywords:** technical documentation best practices, docs-as-code workflow, production incident runbooks, self-serve engineering onboarding, agile definition of done, pull request documentation validations, developer enablement, system architecture documentation, api integration tutorials, markdown documentation formatting, continuous integration doc checks, engineering visibility, conceptual vs task-based documentation, knowledge sharing culture

## Chapters

1. **Introduction and the value of runbooks** (00:00) — How clear runbooks help mitigate production incidents and reduce downtime during out-of-hours on-call shifts.
1. **Identifying common types of technical documentation** (02:50) — How system design briefs, project readme files, and onboarding outlines share essential team knowledge.
1. **Debunking the myth of self-documenting code** (04:49) — Why code syntax alone cannot convey business logic, architectural intentions, or reasoning behind complex implementations.
1. **Career and team benefits of writing documentation** (05:39) — How documenting internal processes reduces daily interruptions while increasing team velocity and individual visibility.
1. **Adapting technical documentation for diverse audiences** (12:31) — Identifying what concepts must be covered for internal operating systems versus external API consumers.
1. **Establishing centralized documentation and storage standards** (16:23) — How adopting a single knowledge base minimizes context switching and helps teams locate resources quickly.
1. **Formatting documentation for fast developer scannability** (17:23) — Structuring technical guides with clear headings, short sentences, and color emphasis to support quick developer scanning.
1. **Incorporating docs as code into CI/CD pipelines** (20:08) — Applying markdown and automated pipeline validations to treat documentation quality as strictly as software tests.
1. **Separating technical concepts from instructional tasks** (22:31) — Structuring content to decouple high-level architectural reasoning from actionable step-by-step procedure guides.
1. **Enforcing documentation requirements in operational workflows** (25:23) — Equipping engineering managers to require updated documentation as an undeniable part of the definition of done.
1. **Addressing AI assistance and documentation tooling** (27:27) — Addressing audience questions about using large language models and tracking documentation updates across various code repositories.

## Related Moments

- [Boosting team productivity with comprehensive engineering documentation](https://www.wearedevelopers.com/videos/927-documentation-as-a-tool-introducing-documentation-driven-development) (from "Documentation as a Tool: Introducing Documentation Driven Development")
- [Designing technical documentation for cross-functional audiences](https://www.wearedevelopers.com/videos/379-communicate-efficiently-with-software-architecture-diagrams) (from "Communicate efficiently with Software Architecture Diagrams")
- [Treating technical documentation as a core engineering practice](https://www.wearedevelopers.com/videos/727-the-abc-of-dx) (from "The ABC of DX")
- [Treating developer documentation as a primary product](https://www.wearedevelopers.com/videos/1801-api-first-how-twilio-designs-for-developers-justin-kitagawa-twilio) (from "API‑First: How Twilio Designs for Developers - Justin Kitagawa (Twilio)")
- [Building an engineering culture around reading and writing documentation](https://www.wearedevelopers.com/videos/798-continuous-documentation-for-your-code) (from "Continuous Documentation for Your Code")
- [Driving business objectives through comprehensive technical documentation](https://www.wearedevelopers.com/videos/925-i-will-remember-that-and-other-lies-why-documentation-matters-and-it-makes-your-apps-better) (from ""I will remember that" and other lies - Why documentation matters and it makes your apps better")

## Related Articles

- [The real reason we document our code](https://www.wearedevelopers.com/magazine/518-the-real-reason-we-document-our-code)
- [Humanizing Your Documentation](https://www.wearedevelopers.com/magazine/133-humanizing-your-documentation)
- [Technical Documentation For Developers](https://www.wearedevelopers.com/magazine/128-technical-documentation-for-developers)
- [7 Best Steps For Writing Good Software Technical Documentation](https://www.wearedevelopers.com/magazine/113-7-best-steps-for-writing-good-software-technical-documentation)

## Related Jobs

- [Manager, Technical Support](https://www.wearedevelopers.com/jobs/ext/737543-manager-technical-support) at **Twilio**
- [Tribe Lead - ( Software) Engineering Centre of Excllence](https://www.wearedevelopers.com/jobs/ext/1475530-tribe-lead-software-engineering-centre-of-excllence) at **SD Worx**
- [Staff Developer Advocate, GitHub Security Lab](https://www.wearedevelopers.com/jobs/ext/1921051-staff-developer-advocate-github-security-lab) at **GitHub**
- [Senior Software Engineer](https://www.wearedevelopers.com/jobs/ext/15942-senior-software-engineer) at **GitHub**
- [Staff Software Engineer, Database Infrastructure](https://www.wearedevelopers.com/jobs/ext/1470125-staff-software-engineer-database-infrastructure) at **GitHub**
- [Senior Software Engineer, Enterprise Products](https://www.wearedevelopers.com/jobs/ext/1841248-senior-software-engineer-enterprise-products) at **GitHub**