Writing Documentation When You Aren't a Technical Writer
I'm a technical writer. I write the docs for Chrome DevTools and Lighthouse.<p>The tips in this article are mostly fine. Nothing controversial there. It has some good advice, but ironically, the article itself doesn't follow its own advice.<p>> The first two paragraphs must state the most important information.<p>The most crucial skill for creating quality documentation is to <i>know your audience</i> and then write for that particular audience. What knowledge are they bringing into the doc (and therefore you don't need to cover)? What knowledge are you assuming that they know? What if they don't have that knowledge? Hint: They'll probably find your doc confusing and frustrating. What is their likely emotional state going into a doc? E.g. if you're documenting an error code there's a higher chance that they're panicked, so don't waste their time! Given a particular audience, what exactly is "the most critical information"?<p>"Know thy audience" is one of those concepts where, the more you think about it, the less you realize you know. It's a lifelong journey. But the more you focus on this concept, the better <i>all</i> of your communication will get.<p>I could go on for years about all sorts of interesting tips for improving your writing, but it's all a waste of time if you don't have an overarching guiding principle. And that principle is to know and write for your audience.