How to write technical posts so people will read them (2019)
This article talks about formatting and other superficial stylistic issues.<p>The main challenge of writing a technical post is deeper: who is your audience? And how much do you assume they already know?<p>The temptations are to take extremes: either you have to reexplain everything in the universe, or you assume you're talking to someone who already knows everything.<p>I've found this surprisingly hard to balance. In the end, though, I decided it's always better to err on the side of comprehensibility. This is true even for highly technical writing like scholarly articles.<p>One way that I've found works is to first write it out, stream of consciousness. Invariably this will be too technical. That will be obvious after waiting a day or two and revisiting it. Then build a bridge between where you are now and where the article is, with a more general introduction, and revise the body to flow with that new introduction. It's okay to push details to a supplement or appendix or footnote if necessary.