Anti-patterns in software blogging(refactoringenglish.com)
320 points by ilreb 6 days ago | 146 comments
tl;dr: Common software blogging mistakes include meandering intros that fail to quickly tell readers who the post is for and what they'll gain, assuming readers share your exact knowledge, over-relying on links instead of briefly explaining terms, and treating posts as sequels requiring prior reading. Writing should be conversational rather than stiffly formal. On the technical side, test for mobile overflow and avoid low-contrast fonts—browser dev tools can catch both.
HN Discussion:
  • ↑Education should be upfront and repetitive, not structured like storytelling with twists
  • ↑These writing principles apply broadly beyond blogging to all written communication
  • ↑Failing to connect topics to readers' existing knowledge is the most damaging mistake
  • •LLM-generated blogs are proliferating and making writing quality worse
  • ~The 'write like you speak' advice is problematic, especially for non-native speakers