The Problem with Technical Comparisons: How Writing About 'Foo vs Bar' Can Alienate Your Audience
By
ysangkok
Crisped on the outside, thoughtful enough on the inside.
Summary
The article discusses the pitfalls of writing technical comparisons that alienate parts of the audience, using the example of comparing 'foo' and 'bar' where some readers might know 'bar' as 'frobnicated foo'. It warns that such comparisons can confuse and alienate readers who have different terminology or strong opinions about technical concepts, suggesting writers should be careful with comparative technical writing to avoid excluding knowledgeable audience members.
Key quotes
· 4 pulledTry to avoid writing things like this: 'Foo is bad, and bar is better; here is why ...'
Because inevitably, somebody will respond: 'wait, I was confused, but I think I've figured it out: what you're calling a 'bar' I know as a 'frobnicated foo''
A frobnicated foo is obviously a type of foo.
So writing things like that alienates a core part of your audience: the people who have strong opinions on frobni
You might also wanna read
Sulat: Technical Research Publication on AI and Systems
This appears to be a Substack publication landing page or promotional content for "Sulat" by JP, which focuses on technical research and wri
sulat.com·3mo ago
Analysis of Org Mode Syntax as a Reasonable Lightweight Markup Language
The article argues that Org mode syntax is the most reasonable lightweight markup language for text, comparing it favorably to alternatives
The Limitations of Markdown for Technical Documentation and Better Alternatives
The article critiques Markdown's limitations for technical documentation, arguing that while Markdown is popular and human-readable, it lack
newsletter.bphogan.com·6mo ago
The Advantages of reStructuredText (rST) Over Markdown for Technical Writing
The author expresses a strong preference for reStructuredText (rST) over Markdown, citing their experience using Sphinx for writing books li
buttondown.com·9mo ago
NVIDIA Announces "Hack for Impact" London Event for Autonomous AI Agent Development
NVIDIA is hosting a "Hack for Impact" event in London, challenging participants to build autonomous agentic applications using open-source m
luma.com·3h ago
Four practical steps to control Azure Foundry token costs for agentic AI workloads
This article provides practical guidance on controlling token costs in Microsoft Azure Foundry, particularly for agentic AI workloads where
purplefrogsystems.com·4h ago