How to write technical posts so people will read them (2019)
This article talks about formatting and other superficial stylistic issues.The main challenge of writing a technical post is deeper: who is your audience? And how much do you assume they already know?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.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.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.