Technical Writing

Technical Writing

Write articles that go deeper than features and into how things actually work. For architecture posts, internals explainers, engineering decision writeups, and anything where the reader wants to understand the system, not just use it.

When to Use This vs Content Writing

Content writing covers announcements, launches, partnerships, and general brand content. Use that for "what's new."

This skill is for "how it works." When the reader needs to understand a mechanism, a design decision, or the internals of a system to get real value out of it. The audience is power users, developers, and technically curious people who already use the product and want to go further.

If the article would feel at home on an engineering blog or in a "best practices" series, it belongs here.

Post Types

Not every technical article is an architecture post. Match the structure to the content:

1. Architecture / System Design

Explains how a system is built and why decisions were made. Our default type.

1. Problem we needed to solve
2. Constraints and requirements
3. Options considered
4. Architecture chosen (with diagram)
5. Trade-offs we accepted
6. Results and lessons

2. Deep Dive / Explainer

Explains a concept, technology, or mechanism in depth. Not about a whole system — about one thing and how it works.

1. What is [concept] and why should you care?
2. How it works (simplified mental model)
3. How it works (detailed mechanics)
4. Real-world example
5. Trade-offs and when NOT to use it
6. Further reading

3. Tutorial / How-To

Step-by-step instruction. The reader should be able to follow along and build something.

1. What we're building (with screenshot/demo)
2. Prerequisites
3. Step 1: Setup
4. Step 2: Core implementation
5. Step 3: ...
6. Complete code (link to repo)
7. Next steps / extensions

Tutorial rules: show the end result first, every code block must be runnable, include error handling, explain the "why" not just the "how."

4. Postmortem / Incident Report

Describes what went wrong, why, and what was fixed.

1. Summary (what happened, impact, duration)
2. Timeline of events
3. Root cause analysis
4. Fix implemented
5. What we're doing to prevent recurrence
6. Lessons learned

5. Benchmark / Comparison

Data-driven comparison of tools, approaches, or architectures.

1. What we compared and why
2. Methodology (so results are reproducible)
3. Results with charts/tables
4. Analysis (what the numbers mean)
5. Recommendation (with caveats)
6. Raw data / reproducibility instructions

The Pattern (Architecture Posts)

Every architecture article follows the same shape, derived from what actually performed well:

1. Title as series entry. Format: The Architecture #N: [Topic] or a series name that signals recurring depth. This sets expectations and builds a readership that comes back.

2. Subtitle as thesis. One line under the title that states the core argument. Not a summary of what the article covers, but the point it makes. Example: "Most people run Starchild on default settings. This is about the two commands that change that."

3. Open with the gap. Start by naming what most people do (the default, the obvious path) and why it's suboptimal. This creates stakes without being dramatic. The reader should feel the tension between how they currently operate and how they could.

4. One mechanism per section. Each section explains exactly one thing: what it is, why the default is insufficient, how to configure it differently, and what changes when you do. Don't bundle multiple features into a single section even if they're related.

5. Code blocks as commands, not concepts. Show the exact thing the reader would type or the file they'd edit. Not pseudocode, not abstract examples. Real commands, real file paths, real config. The article should be usable as a reference while reading it.

6. Close with "why these first." A brief section that connects the pieces and explains the priority order. Not a summary, but a justification: why these features matter together, why this sequence, what becomes possible once you have them dialed in.

7. Series hook. End with a one-liner about what's next in the series.

Depth Per Topic

The v1 draft covered six features in one article. The v2 covered two. The v2 performed better because two topics at real depth beats six at surface level.

Rule of thumb: 2-3 topics per article, each with enough detail that a reader could actually implement what you're describing. If you can't write 200+ words of substantive content about a feature, it doesn't belong in a technical article. Save it for a changelog or a feature list.

Word Count by Type

Audience Level

State your assumed audience level explicitly at the start of the article:

"This post assumes familiarity with Docker and basic Kubernetes concepts. If you're new to containers, start with [our intro post]."

Voice and Style

All rules from the content-writing skill apply, plus these additions specific to technical content:

Be opinionated about defaults. Technical articles exist because defaults are often wrong for power users. Say so directly. "That is waste" is better than "This may not be optimal."

Explain the why, not just the what. Every feature description needs a reason it exists. Don't just say "Smart Routing routes messages to different models." Say why one model for everything is a problem worth solving.

Use concrete before/after states. Show the world as it is, then the world as it could be. "Every message hits the same model, whether you're asking what time it is or debugging a 300-line async crawler" is more compelling than "Smart Routing optimizes model selection."

No hedging. Don't say "you might want to consider" or "it could be helpful to." Say "do this" or "this is worth setting up." Technical readers want conviction, not options.

Write from experience. Only write about what you've done in production. If exploring, say so. The sentence "We haven't tested this at scale yet, but here's our thinking" is better than pretending certainty you don't have.

Commands and file paths are content. Format them as code blocks. They're the most valuable part of the article because they're immediately actionable.

Anti-AI Formatting Rules

Never use em dashes (—). They're an AI tell. Use commas, parentheses, or restructure the sentence instead.

Bad: "The vault—which manages liquidity automatically—reduces the need for manual intervention." Good: "The vault manages liquidity automatically, which reduces the need for manual intervention."

Never use horizontal dividers (---) between sections. They make content look AI-generated. Let the headers do the work of separating sections.

Write flowing sentences, not choppy ones. Combine related ideas into longer sentences that flow naturally from one point to the next. Short choppy sentences read like AI output.

Bad (AI-sounding): "The system is efficient. It saves gas. Users benefit from lower costs. This improves the experience." Good (natural flow): "The system is more efficient because it batches transactions together, which means users pay less gas and get a better experience overall."

Never use the "It's not X. It's Y." construction. This is the single most recognizable AI tell. Every ChatGPT output leans on it. Restructure the sentence entirely.

Bad: "It's not just a wallet. It's a financial operating system." Bad: "This isn't automation. It's augmentation." Bad: "It's not about the tool. It's about the workflow." Good: "The wallet doubles as a financial operating system, handling everything from transaction signing to portfolio rebalancing." Good: "The system augments human decisions rather than replacing them."

Round numbers to meaningful precision. $1.2M, not $1,234,567. Compare to benchmarks when it helps the reader understand scale.

Additional Word Swaps

Hard avoid: exciting, massive, huge, moon, WAGMI, LFG, best-in-class, world-class, ecosystem play.

Words to Cut

Hedging: When It's Appropriate

Hedging is weak in most cases, but correct when:

• Genuinely uncertain outcomes ("We haven't tested this at scale yet")
• Multiple valid approaches ("Either approach works; pick based on your team's familiarity")
• Environment-specific behavior ("This may vary depending on your Kubernetes version")

Before/After Transformations

Code Examples

Good code block format:

# Exponential backoff with jitter
def calculate_retry_delay(attempt: int, base_delay: float = 1.0) -> float:
    delay = base_delay * (2 ** attempt)
    jitter = random.uniform(0, delay * 0.1)
    return delay + jitter

# Usage
delay = calculate_retry_delay(attempt=3)  # ~8.0-8.8 seconds

Diagrams and Visuals

One diagram is worth 500 words of description. If you're describing a system with more than three components, draw it instead of narrating it.

Common Mistakes

Editing Checklist

Before publishing:

• [ ] Title promises something specific
• [ ] Subtitle states the thesis, not the topic
• [ ] Opening hooks in 30 seconds (the gap, the problem)
• [ ] Audience level stated explicitly
• [ ] Claims backed by examples, code, or numbers
• [ ] All unnecessary words cut (see Words to Cut)
• [ ] Code examples tested and runnable
• [ ] Trade-offs section present and honest
• [ ] Takeaway crystal clear
• [ ] Would send to a respected colleague without embarrassment

What to Ask For

Before writing, confirm:

1. The product or system being explained 2. Which features or mechanisms to cover (2-3 max per article) 3. The post type — Architecture, Deep Dive, Tutorial, Postmortem, or Benchmark 4. The series name if this is part of a recurring set 5. Audience level — are they users who want to configure, or developers who want to understand the architecture? This changes how deep you go on implementation details.

If the user just says "write a technical article about X," pick the 2-3 most impactful subtopics and propose them before writing.

Output Format

Deliver both:

1. Article — formatted with headers, code blocks, ready for CMS or Paragraph 2. Tweet thread — 3 tweets max: hook (the gap), mechanism (the core insight), outcome (what changes + link)

References

Load on demand:

• Starchild technical article examples: references/starchild-examples.md

Starchild Technical Article Examples

Example 1: The Architecture #1 — Smart Routing and the Doctor

This was the published version (v2). It covered two features at depth rather than six at surface level.

What worked:

• Series framing ("The Architecture #1") set expectations for recurring content
• Subtitle stated the thesis directly: "Most people run Starchild on default settings. This is about the two commands that change that."
• Each feature section explained the default problem, the command to fix it, and the concrete change
• Code blocks showed exact commands (/model smart, /doctor)
• "Why These Two First" section justified the priority order
• Series hook at the end: "Next up: Scheduled Tasks and Silent Automation"

Full text preserved in: output/technical-blog-draft-v2.md

Example 2: The Architecture (v1 draft) — Six Features

This was the earlier draft covering Smart Routing, /doctor, Push Notifications, Memory, Skills, and Scheduled Tasks.

What changed between v1 and v2:

• v1 covered too many topics. Each section was 3-5 paragraphs, enough to describe but not enough to actually teach
• v2 cut to two topics and gave each room to breathe with examples, edge cases, and concrete configuration
• v2 added the "Why These Two First" connector section, which v1 lacked
• v2's subtitle was a thesis; v1's subtitle was a description ("A Starchild Best Practices Guide")

Lesson: Depth beats breadth. Two features a reader can actually configure beats six features they'll forget.

Full text preserved in: output/technical-blog-draft.md

Structural Pattern (extracted from both)

# [Series Name] #[N]: [Specific Topic]

*[Subtitle that states the thesis, not the summary]*

## [Feature 1]: [Short Name]

[Open with the default behavior and why it's suboptimal]
[Show the command or configuration that changes it]
[Explain what changes concretely — before/after]
[Edge case or override worth knowing about]

## [Feature 2]: [Short Name]

[Same structure as Feature 1]

## Why These [N] First

[Connect the features, justify the priority, show what becomes possible]

*[Series hook — what's next]*