| 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. |
On that note though, there is one thing that people have been doing for the past 5 or so years, maybe a bit more, with the formatting when they write online. In particular I see it often on Medium.com
They use blockquote to highlight some piece of their text. But the text in the blockquote is not a quote. Neither from elsewhere nor from their own text.
This annoys me.
AFAIK, blockquote has a history in the printed press of being used to catch your eye when you flick through a newspaper, so that you would want to buy the paper and read the article on that page. And the text in the blockquote was extracted from the text itself. Often from a part of it where a person that was interviewed said something that the editors found interesting. At least, that’s how I remember it.
Another type of use it is suitable for is to distinguish something quoted from elsewhere from the rest of the text.
But the way that it is being used now, it confuses and annoys my brain every time.