Revised December 2025: Simplified for readability. Full algorithm in addendum.

Writing technical articles is an art. This is wrong. It’s a methodological process. And this isn’t new.

Effective technical writing draws from centuries of tradition: from Aristotle and Cicero to modern cognitive research. You’ve likely seen this in action, even if authors weren’t consciously following a framework.

Look at any successful technical article. The structure is there:

• David Crawshaw’s “How I Program with LLMs” uses clear signposting (he outlines three ways to use LLMs) and ends with a concrete call to action.
• The S3 laptop rant “State of S3” follows classical structure: three arguments, rebuttals, and a closing that urges action.

What’s the common thread? These articles follow a process, whether the authors knew it or not.

Writing an article is applying an algorithm: define your inputs, process them through a sequence of logical steps, and arrive at the output. Each step corresponds to a clear function or subroutine. (See the full algorithm in the addendum.)

Why am I formalizing this?

I frequently publish technical articles in the IT/OT domain, some featured on HackerNews. Colleagues often ask how I write well-researched content while running a company. I combine classical rhetoric with LLMs (o1 <3). The result: quality articles without AI’s usual problems.

This article formalizes my process. It helps anyone with insights who struggles to write them down.

To prove it works, I’ll apply it to this article, so you can watch each step unfold in real time.

Following classical rhetoric, I’ll present three arguments (tutorials call them “steps,” explainers call them “key concepts”; same structure, different names):

1. Lay the Foundation, which shows how to define your three core arguments based on your subject, message, and call-to-action, using creativity and filter techniques
2. Build Rhetoric, which uses classic concepts like ethos, pathos, logos to shape your arguments; and
3. Refine for Readability, which uses techniques inspired by modern research to ensure that your work can be understood by the reader and sparks joy.

Why three? Working memory holds 3-4 items at once. More on this in the Readability section.

Master this, and writing becomes faster. Your ideas get read. Colleagues start asking how you do it.

Ready to see how it comes together? Let’s start with the inputs.

Lay the Foundation (Your Original Ideas)

Start with your inputs: subject, call-to-action, and message. Then find your arguments.

Define your subject: what your article is about. Be specific. “Technical writing” is too broad; “writing frameworks for technical articles” works.

Decide what you want readers to do after reading. This is your call-to-action. As a CTO, most of my articles subtly nudge readers toward using our product. CTAs work for non-promotional articles too: guide readers to “check out my bio,” “watch my latest conference speech,” or “try out this open-source project.” Avoid generic prompts like “Contact us now!” Technical readers ignore them. They won’t call you after one article. Offer a small next step: a demo link, deeper content, or a GitHub repo. Build trust gradually.

Craft your message: the central insight in a short sentence, ideally six words or less and free of clichés. Include a subtle rhetorical device if it fits.

With these defined, we can find your arguments.

“I’m writing a step-by-step guide or informational piece; I don’t need arguments.”

Arguments aren’t only for debates. An argument is a claim supported by reasons ¹. This means that effective communication, regardless of format, involves presenting claims and supporting them with reasons.

In technical writing, these arguments manifest differently depending on content type. Tutorials present each step as a claim about what readers should do, with reasons explaining why. White papers build claims about industry trends or product benefits, substantiated by research. Explanatory articles make claims about how things work, supported by detailed explanations. Case studies frame project phases as claims about actions and outcomes, backed by real-world evidence.

The Toulmin System² breaks down arguments into five components: a claim (the main point you want readers to accept), grounds (evidence that supports it), a warrant (the assumption connecting grounds to claim), backing (additional justification for the warrant), and rebuttal (recognition of counterarguments). You don’t need all five for every argument, but knowing the framework helps you spot weak spots in your reasoning.

Good articles present novel ideas. Creativity research ³ divides thinking into divergent (expand ideas) and convergent (narrow down). This is the double diamond model (Fig. 2) ⁴: two diamonds showing expansion and narrowing phases.

Choose a creativity technique to brainstorm at least six different arguments, steps, or key concepts for your article. Brainstorming works for most people. Some other accepted techniques include mind mapping, 6 thinking hats, or morphological boxes⁵.

Creativity can be systematized. Techniques like brainstorming are widely used, though empirical evidence is limited ^{5 6}.

At this stage, anything goes: gather a broad range of ideas without worrying about relevance or feasibility. For example, you might brainstorm ideas like:

• “Define inputs first”
• “Explore structure and prose (introductions, transitions, signposts)”
• “Emphasize original insights (why new facts matter)”
• “Discuss LLM usage (can AI help with clarity?)”
• “Refine readability (bullet points, visuals, concise language)”
• “Address counterarguments (alternative methods, pitfalls)”
• “Cats with laser eyes”

Some ideas will seem silly. That’s fine; quantity first, refinement later.

You’ve brainstormed. Now converge: group related ideas, check if they are MECE, narrow them down to three arguments, and add evidence.

Look for patterns or themes that can be combined. For example, you might identify clusters like:

• “Inputs and foundational concepts”
• “Structuring content for clarity”
• “Ensuring readability and engagement”
• “LLM usage”
• “Weird stuff”

If you’ve generated supporting points for a white paper, identify themes or recurring concepts. And if “cats with laser eyes” doesn’t support your message, drop it or mention it briefly as a playful anecdote.

Use MECE (Mutually Exclusive, Collectively Exhaustive), popular at McKinsey, to ensure no overlap and no gaps ⁷.

First, ensure items are mutually exclusive: each covers a unique idea. For example, “How to use LLMs” and “Making it pretty” overlap because LLMs can help refine prose. Merge or exclude overlapping points to avoid redundancy.

Second, ensure points are collectively exhaustive; together, they cover all critical aspects of your message.

If the message is “Writing is like coding,” then arguments about readability and structure are critical. However, a stand-alone discussion of LLMs might be tangential unless it directly supports the main topic.

Narrow down to three claims, the most important arguments. For tutorials with more steps, cluster into three overarching categories. Why three? Working memory holds 3-4 items at once (see the Refine for Readability section).

Back up each point with grounds: data, anecdotes, or examples. In tutorials, explain why each step matters. Address alternatives or misconceptions with rebuttals.

Evidence can take many forms ¹: personal experience that illustrates your point, field observations or research findings, data from interviews and surveys, credible published sources, expert testimony, statistics for quantifiable support, hypothetical examples that clarify abstract ideas, or reasoned sequences connecting concepts logically. The best arguments weave several types together.

Optionally, add warrants and backing. Successful arguments need a claim, grounds, and a warrant (sometimes implicit). When readers might question your assumption, state it explicitly and provide backing; this reinforces the connection between your grounds and your claim.

You’ve defined inputs, brainstormed angles, and selected three MECE-compliant arguments backed by evidence. That’s a solid foundation. The Toulmin System keeps your arguments clear and persuasive.

Even the best ideas won’t resonate without structure. Let’s see how rhetoric glues your arguments together.

Build Rhetoric (Your Logical Structure)

Rhetoric glues your arguments together. Cicero’s famous works ⁸ break down any speech into six parts: the exordium captures attention and establishes credibility; the narratio provides background; the divisio signals the structure ahead; the confirmatio presents arguments with evidence; the refutatio addresses counterarguments; and the peroratio closes with emotional appeal and reiterates the main point.

Why does this matter? Structure helps readers follow your logic. Background and signposting break complex topics into manageable parts. Summaries and transitions help readers remember key points. We’ll map the inputs we defined earlier onto this framework.

How do you structure the introduction? Start with a hook: a compelling opening that captures attention. Keep it short and intriguing, avoiding clickbait. Include a personal anecdote if relevant, but keep it brief. Return to this hook at the end for closure.

Establish ethos early. In classical rhetoric, founded by Aristotle ⁹, ethos demonstrates why the audience should care about your perspective. Show your credibility through experience, research, or unique insight. Don’t overdo it; a brief mention is enough.

Provide background to contextualize your article. Why does this topic matter now? What gap in knowledge are you addressing? Then add a signpost: introduce your main points or steps so readers know what’s coming. Without it, readers get lost in longer articles. Use clear language like “This article presents three key arguments…” or “We’ll break this problem down into three steps…”

Add a subtle emotional pull that connects your topic to the reader’s goals or challenges. This isn’t manipulation; it’s showing readers why they should care. Then craft a smooth transition that bridges from introduction to body.

How do you structure the conclusion? Return to your opening hook. Bring closure to the story or question you posed at the start. This creates a satisfying sense of completeness. End with a stronger emotional push that connects to your call-to-action, giving readers both the logical reason and the emotional impetus to take the next step.

How do you enrich your arguments? Provide background to prepare readers for complex evidence. Acknowledge limitations with qualifiers like “typically” or “in most cases.” Recap key points at section ends to reinforce how evidence supports claims. Connect sections with transitions that ease cognitive load and prepare readers for what’s next.

Hook for attention, ethos for credibility, signposts for clarity, pathos for emotion. Context, summaries, and transitions help readers offload details from working memory.

So how do you polish the result?

Refine for Readability (Why It Sparks Joy)

Final step: make it readable. Even perfect logic fails if buried in 5,000-word paragraphs.

What is readability? It’s how easily readers digest text. Humans can’t juggle a dozen concepts at once ¹⁰.

Recent reviews on working memory ¹¹ and cognitive load ^{12 13} highlight that 3-4 items is the upper limit that most people can hold in working memory before overload sets in.

Introducing complex terms without explanation increases extraneous cognitive load (mental effort from poor presentation rather than difficult content).

How does cognitive load work? Working memory temporarily holds and processes information, but its capacity is limited; too much at once causes confusion. Cognitive load theory ¹³ breaks this down into three types: intrinsic load comes from the material’s inherent complexity; extraneous load comes from poor presentation like bad organization or unnecessary jargon; and germane load is the useful effort of building mental schemas.

Technical articles have high intrinsic load by nature. Your job is to minimize extraneous load so readers can devote their mental effort to germane load: actually understanding and applying your ideas.

If your arguments are MECE (from the Foundation section), you’ve already cut mental overhead. And by using signposts, readers don’t have to track what’s coming; the structure does it for them. Rehearsal promotes germane load and prevents overload: add brief summaries at section ends or transitions at section starts. Clear headings reinforce this structure; we’ll cover formatting specifics below.

How should you handle jargon? Eliminate unnecessary jargon. Obscure jargon kills good structure. Readers backtrack. Introduce technical terms only when necessary and define them immediately.

It’s perfectly fine to use jargon. Ensure it is necessary. And be sure that your audience knows it. Not all “standard” jargon is universal across sub-domains.

For example, if you use the formal term “conditional statement” in a Go tutorial, clarify with a quick note that it refers to “if-statements,” a term that’s often misunderstood by juniors (I’ve lost count of how many times I’ve heard “if-loops”).

Even technical audiences vary in background. Format definitions so advanced readers can skip them.

For example, consider how to explain MQTT.

Bad:

MQTT is an OASIS standard messaging protocol for the Internet of Things (IoT). It is designed as an extremely lightweight publish/subscribe messaging transport that is ideal for connecting remote devices with a small code footprint and minimal network bandwidth.¹⁴

Potential confusion: “What is OASIS?” “What does publish/subscribe mean?” “Why should I use it?”

Better:

MQTT (Message Queue Telemetry Transport) is a protocol designed for communication between devices. It uses a publish/subscribe architecture, where devices (publishers) send messages to a central message broker. Other devices (subscribers) that are interested can then receive the messages from the broker.

Compared to other architectures, publish/subscribe allows for near real-time data exchange and decoupling between devices, which makes it easy to add or remove devices without disrupting the network.

Among publish/subscribe protocols, MQTT is simple and lightweight. This allows millions of low-power, memory-constrained devices (common in Internet of Things (IoT) applications) to communicate with each other.

Here, the definitions arrive exactly when needed, not hidden in footnotes or introduced 20 paragraphs later. This reduces extraneous load.

What formatting practices help? Good formatting reduces cognitive load; readers see where they are and what’s next. Below are best practices drawn from common technical writing standards and research-tested web guidelines ¹⁵.

A few formatting guidelines:

1. Vary sentence length. Short sentences drive forward; longer ones add detail. Keep paragraphs short, a few sentences each. Use active voice. Cut filler like “in order to” or “basically”.

2. Use clear headings. Your main arguments (MECE, no more than three) each deserve a clear H2; use H3 for supporting details.

3. Use visuals. Break up large blocks of text with images, but avoid clutter. Don’t place text over images. Label them clearly.

4. Use structural variety. Bullets, numbers, quotes, code blocks, and white space all help readers scan and absorb content.

   Use quotes to highlight important statements or external sources.

   fmt.Println("Code blocks make abstract concepts concrete.")
   

   On smartphones, include a visual or structural element about every screen length of text.

5. Bold over italics. Use bold to emphasize key words. Avoid underlining; it’s hard to read.

How do you revise effectively? Good articles need revision. Expect to loop back through the framework. It’s your checklist.

Fresh eyes help. Try reading from end to beginning to spot inconsistencies, step away briefly for clarity, or use AI to identify weaknesses you might have overlooked. If a section’s end repeats the next section’s start, merge them.

For polish, use tools like DeepL Write to catch errors and improve sentence structure. Define specialized terms when first used and revisit them for consistency. Reading aloud catches awkward phrasings and run-on sentences.

Readability makes technical content accessible. It completes the work from the earlier sections.

Conclusion

See? By applying a clear, repeatable process, we’ve shown that writing technical articles isn’t just “art”; it can be learned by anyone willing to follow the steps.

This article followed its own framework. Apply this process to transform technical expertise into clear, engaging articles.

The algorithm in action: inputs, process, output. Each step is learnable.

Your ideas deserve to be read. Structure them well, and they will be.

Now apply this process to your next article. Open your preferred LLM (Claude, ChatGPT, etc.), paste this framework article alongside your draft, and ask: “Apply this framework to improve my article.” The LLM will identify missing elements and suggest structural improvements.

Addendum: The Full Algorithm

For those who want the complete algorithmic representation, here’s the framework:

1. Introduction:
   • Hook: Capture attention with a strong opening.
   • Ethos: Establish credibility and context.
   • Subject: Define the topic or problem being addressed.
   • Message: Present the central insight or analogy.
   • Background: Provide context or explain why this is relevant now.
   • Signpost: Outline the article structure (e.g., ArgA, ArgB, ArgC).
   • Light Pathos: Subtle emotional appeal tied to the reader’s goals.
   • Transition: Smooth segue into the main content.
2. Argument A, B, and C:
   • Claim: State the main point/step/key concept.
   • Qualifiers: Acknowledge any limitations to your claim.
   • Grounds: Provide evidence or examples supporting the claim.
   • Rebuttals: Address potential counterarguments.
   • (Optional) Warrants and Backing: State and back-up underlying assumptions if needed.
   • Transition: Bridge to the next argument or section.
3. Conclusion:
   • HookFinish: Return to the hook for closure.
   • Summary: Summarize the main points of the article.
   • Message: Reinforce your central insight or analogy.
   • Strong Pathos: Final emotional appeal to motivate action.
   • CTA: End with a clear, actionable step for the reader.

This framework maps each phase of article writing to a clear process. The prose above explains what each step does; this addendum shows how they connect.