The Myth of the "Soft Skill"
Many engineers dismiss writing as a "soft skill" — something to be done after the "real work" (coding) is finished. This is a mistake.
Think of it this way: code is instructions for computers, and documentation is instructions for humans. A compiler will execute your code exactly as written. A human will give up, ask Slack, or make a dangerous assumption if your documentation is unclear. Both audiences need precise instructions; only one of them will tell you when you've failed.
Documentation is the interface between your system and every person who must operate, extend, or debug it. That includes your future self, six months from now, staring at a service you've completely forgotten.
The Cost of Bad Documentation
The consequences of poor documentation are measurable:
- Onboarding time increases. New engineers spend days reverse-engineering what a README could have explained in minutes.
- Incident duration increases. An on-call engineer who can't find the right runbook spends 20 minutes searching instead of 2 minutes fixing.
- Bus factor stays dangerously low. When knowledge lives only in one person's head, that person becomes a single point of failure.
- Repeated questions consume senior engineer time. Every Slack message that starts "Hey, how do I..." is a documentation gap.
The Goal: Clarity, Not Poetry
Technical writing is not about using sophisticated vocabulary or sounding academic. It is the opposite. The goal is to transfer information from your brain to the reader's brain with the least amount of friction — what cognitive scientists call cognitive load — possible.
The metric for good technical writing is time-to-understanding: how long does it take a reader to extract the information they need and act on it? If a reader has to re-read a sentence, you have failed. If they have to open a second tab to understand the first tab, you have failed.
This lesson covers the core principles of clear writing, the modern "Docs as Code" workflow, and how to write runbooks that save lives at 3 AM.