flâneur

To get better at technical writing, lower your expectations

seangoedecke.com · 1,469 words · saved by 1 readers

Technical writing is a big part of a software engineer’s job. This is more true the more senior you get. In the limit case, a principal or distinguished engineer might only write technical documents, but even brand-new junior engineers need to write: commit messages, code comments, PR descriptions and comments, Slack threads, internal announcements, documentation, runbooks, and so on. Whether you write well or badly matters a lot. The primary rule about technical writing is that almost none of your readers will pay much attention. Your readers will typically read the first sentence, skim the next one, and then either skim the rest or stop reading entirely. You should thus write as little as possible. If you can communicate your idea in a single sentence, do that - there’s a high chance that people will actually read it. What if you can’t communicate all the details in so few words? In fact, this is a feature not a bug. You should deliberately omit many subtle details. This is the bigge

Technical writing is a big part of a software engineer’s job. This is more true the more senior you get. In the limit case, a principal or distinguished engineer might only write technical documents, but even brand-new junior engineers need to write: commit messages, code comments, PR descriptions and comments, Slack threads, internal announcements, documentation, runbooks, and so on. Whether you write well or badly matters a lot. Keep it as short as possible The primary rule about technical writing is that almost none of your readers will pay much attention . Your readers will typically read

saved by

related reading