Writing technical articles: explaining complex concepts in plain language, choosing analogies, and designing examples
1. Why technical articles need layers: one concept, three readers
A B2B technical article never has just one reader. Take the same topic, structured data markup: the CFO wants to know whether it can bring in more leads, the CTO wants to know how many engineering hours it takes, and the engineer wants to know how to write the JSON-LD fields. Hand all three the same text and none of them actually understands it.
The core move in layered writing is this: each layer stands on its own. Decision-makers can judge whether it’s worth doing without reading code, engineers can judge feasibility without reading the paper, and implementers can start work without guessing at default values. This aligns with the thinking behind GEO Content Layering— facts, opinions, and promises each stay in their own place, and what AI extracts is the facts layer.
| Reader role | What they care about | Layer | What shouldn’t appear |
|---|---|---|---|
| Decision-makers (CXOs, procurement) | Is it worth the investment, how big is the risk | Analogy layer | Code, formulas, parameter tables |
| Technical leads (CTOs, architects) | Feasibility, timeline, boundaries | Example layer | Over-explaining the basics |
| Implementers (engineers, ops) | How to fill in fields, what the default values are | Formula layer | Vague “consider optimizing” advice |
This is also how technical articles build E-E-A-T: you give precise parameters at the expert layer and an honest judgment at the decision-maker layer, and you don’t pretend to know more than you do at either. For how to build credibility signals, see E-E-A-T: credibility signals for B2B content.
2. Choosing analogies: use the reader’s industry, not the author’s
Analogies are the easiest tool to misuse in technical writing. A good analogy lets a non-technical reader grasp a concept in 10 seconds; a bad one sends them off with the wrong mental model, and by the time you correct it, it’s too late.
The first rule of picking an analogy is to use a scene your reader knows, not one you know. Explaining APIs to a manufacturing audience? Skip the restaurant menu and use the conveyor belt between workstations on a production line. Explaining CDNs to a SaaS audience? Skip the delivery warehouse and use the front-desk filing cabinet in an office. Your reader’s daily work is the best analogy library there is.
| Technical Concept | Common bad analogies | Good analogies (by industry) | Risk of misleading |
|---|---|---|---|
| API | Restaurant menu | Conveyor belt between workstations | A menu is about choice; a conveyor belt is about asynchronous flow |
| CDN caching | Delivery warehouse | Front-desk filing cabinet | A warehouse is about logistics; a front desk is about grabbing what’s nearby |
| JSON-LD | Product manual | An ID card for search engines | A manual is about detail; an ID card is about standard fields |
| Retry mechanism | Redialing a phone call | A production line auto-resetting after a fault | Redialing involves a person; auto-reset is automated |
Scenario example: you need to explain the LCP metric in Web Vitals to a German auto parts customer. Don’t say “LCP is how fast a page opens” — that’s just restating it.
Say: “LCP is the moment the user sees the main image actually light up — like the time it takes for the indicator light at a key workstation to go from red to green. Past 2.5 seconds, the whole line stops.” This analogy ties the technical threshold to the customer’s daily operations, so decision-makers can judge it directly.
The red line for analogies: they answer “what is it,” never “how is it calculated.” The moment an analogy is used to explain numerical relationships, it starts to mislead. Use a faucet to explain bandwidth, for example, and readers will assume traffic is continuous — but networks are packet-switched. In cases like this, switch to examples immediately.
3. Example design: minimal and runnable, working in 5 minutes
Examples aren’t decoration — they’re the most convincing part of a technical article. A three-line code example that runs beats a thousand words of conceptual explanation. But a badly written example backfires too: toy examples hide edge cases and let engineers assume your approach is just as simple in production.
A good example meets these standards: what the input is, what the output is, and the reader can get it running in their own environment within 5 minutes. No more than 3 lines of code, no more than 2 dependencies, and environment assumptions stated at the top. Any example that needs Docker installed, a cloud account registered, or half an hour of running before you see a result doesn’t count as a good example.
| Example type | Best for | Size limit | Must include |
|---|---|---|---|
| Concept illustration | Analogy layer | A paragraph or an image | Everyday scenario + mapping |
| Code snippet | Example layer | ≤10 lines | Input/output + comments |
| Config example | Example layer | Complete and paste-ready | Defaults + explanatory comments |
| Boundary conditions | Formula layer | Table or checklist | Invalid input + how it’s handled |
| Performance data | Formula layer | Table of numbers | Environment, sample size, number of runs |
Show, don’t just tell: when you write about Article structured data, don’t just drop in a JSON-LD block and call it done. Start with a 3-line minimal example (name, author, datePublished).
Then add an edge-case table: what if the article has no author byline, what if it’s a syndicated post, what if the date is UTC or local time. After reading that table, engineers know exactly which cases will trigger a Search Console warning.
Counterintuitive point: writing “for brevity we’ve omitted error handling” in your example is the most common self-deception in technical writing. Readers won’t thank you for skipping error handling, they’ll hit that exact gap in production. The right move is to leave a TODO comment in the example saying “add retries and timeouts in production” — one line is enough.
4. Formulas and parameters: give defaults, don’t make readers guess
The thing implementers fear most when reading a technical article: you give the formula but not the defaults. They don’t know where to start tuning the parameters, so they guess. In the formula section, spell out the unit, default value, and tuning range for every variable.
When you write technical content with AI, this step is the easiest to skip — large models are good at explaining concepts, not at giving production-grade defaults. Human review must fill this gap. For which parameters need manual verification, see AI collaboration boundaries in content production.
| Spec type | Fields you must spell out | Example (using LCP) |
|---|---|---|
| Threshold | Good, needs improvement, poor | ≤2.5s is good, 2.5–4s needs improvement, >4s is poor |
| Default | Default values and common tuning directions | Image lazy loading is on by default; above-the-fold images are not lazy-loaded |
| Measurement environment | Device, network, sample size | 4G network, Moto G Power, 75th percentile |
| Units | Milliseconds or seconds, percentage or decimal | CLS uses a decimal from 0 to 1, not a percentage |
Citing your data sources is mandatory at this level. Every threshold and default value you reference must trace back to official documentation or a reproducible test. For how to manage sources, see Source Management: Expert Interviews, Data Citations, and Attribution. Expert readers spot unsourced numbers instantly, and it undermines the credibility of the whole article.
5. Pitfalls: four common accidents in technical writing
| Common mistake | Performance | Consequence | Fix |
|---|---|---|---|
| Cross-domain analogies | Using a retail scenario to explain an industrial API | 30% of readers get misled | Use an analogy from the reader’s industry |
| Over-simplified examples | “Error handling omitted” | Readers hit the gap in production | Leave a TODO comment or add an edge-case table |
| Giving formulas without defaults | Variables left dangling | Engineers can’t get started | Add units and defaults to every variable |
| Mixing all three levels together | Code in the first paragraph | Decision-makers bail, experts find it verbose | Split by level, keep each level self-contained |
Keep the tone of technical writing restrained, too. Avoid words like “revolutionary” or “breakthrough” — expert readers are highly sensitive to marketing speak. For tone guidelines, see website copy tone guide. This is especially important when turning a video transcript into a technical article: spoken phrasing has to become written, declarative statements. For the method, see Turning video transcripts into content.
FAQ
Should a technical article assume the reader is an expert?
How do you pick a good technical analogy?
How long should a code example be?
Should formulas in a technical article include default values?
Can analogies mislead readers?
How does a technical article build E-E-A-T credibility?
Final thoughts
The core of technical writing isn’t making the complex simple – it’s layering the complex correctly. Decision-makers need analogies, engineers need examples, implementers need parameters. The three layers stand independently, don’t depend on each other, and let each reader take what they need.
Three steps to get there: this week, pick one existing technical article and rewrite the opening using the three-layer structure. Next week, make every code example runnable in five minutes. In week three, add default values and units to every formula. Do these three things and your technical articles will get read to the end far more often, and the leads they bring in will be better qualified.
One line worth remembering: trust in a technical article comes from not explaining what your reader already knows. Layering isn’t laziness. It’s respect for all three kinds of readers.