technical-writing-best-practices

name	technical-writing-best-practices
description	Use when writing technical articles, tutorials, or documentation. Covers concept ordering, section structure, and active learning techniques.

Technical Writing Best Practices

The Problem

When writing technical content, it's easy to accidentally use concepts before defining them, creating a confusing reading experience where readers encounter undefined terminology.

Symptoms of this problem:

• Readers feel overwhelmed by terminology
• The article feels "disjointed" or hard to follow
• Concepts seem to explain themselves in circles

The Rule: Define Before Use

Every concept must be formally defined before it's used in explanations.

Practical Application

Step 1: Identify All Concepts

Before writing, list all technical terms that will appear:

• Core terms (e.g., KDC, TGT, Ticket, Principal)
• Acronyms (e.g., SSO, LDAP, MITM)
• Protocol-specific jargon

Step 2: Determine Dependency Order

Map which concepts depend on others:

TGT requires understanding of:
  - Ticket (what TGT is a special case of)
  - KDC (who issues TGT)
  - Principal (who receives TGT)

Step 3: Structure Content Accordingly

Recommended order:

1. Intuition/Analogy - Build mental model without jargon
2. Background/History - Why this technology exists
3. Core Concepts - Define all terms formally
4. Concept-to-Analogy Mapping - Connect back to intuition
5. Details - Now safe to use all defined terms freely
6. Advanced Topics - Build on established foundation

Step 4: Validate

Read through and check: "At this point in the article, has every term I'm using been defined?"

Example: Kerberos Article

Before (problematic):

## Amusement Park Analogy
...service center gives you a TGT (Ticket Granting Ticket)...
[TGT used but not yet defined!]

## History
...

## LDAP Relationship
...Kerberos issues TGT for authentication...
[Still using TGT without formal definition]

## Core Concepts
### TGT
TGT is... [Finally defined, but too late]

After (correct):

## Amusement Park Analogy
...service center gives you a "wristband"...
[Pure analogy, no Kerberos terms]

## History
...

## Core Concepts
### TGT
TGT is a special Ticket that... [Formally defined]

## Analogy Mapping Table
| Amusement Park | Kerberos |
| Wristband | TGT |
[Now readers can connect analogy to formal terms]

## LDAP Relationship
...Kerberos issues TGT... [Safe to use - already defined]

Checklist

When writing technical content:

• List all technical terms before writing
• Map concept dependencies
• Keep analogies pure (no mixing with jargon)
• Define core concepts early in the article
• Add a mapping table if using analogies
• Review: every term usage comes after its definition

Anti-patterns to Avoid

1. Premature jargon in analogies: Using technical terms in "simple" examples
2. Forward references: "We'll explain TGT later" - readers need it now
3. Circular definitions: Defining A using B, then B using A
4. Assumed knowledge: Using acronyms without expansion on first use

---

Part 2: Section Structure - Keep Related Content Together

The Problem

When explaining multi-step processes (like protocols), separating "overview" from "details" forces readers to scroll back and forth, losing context.

Symptoms:

• Reader says content feels "overwhelming" or "disconnected"
• Long scroll distances between related information
• Reader loses track of which step they're reading about

The Rule: Group by Logical Unit, Not by Content Type

Instead of organizing by content type (all overviews together, all details together), organize by logical unit (each unit contains its overview AND details).

Example: Protocol Documentation

Before (problematic):

### Message Exchange Flow
  #### Phase 1: AS Exchange (overview)
  #### Phase 2: TGS Exchange (overview)
  #### Phase 3: AP Exchange (overview)
### AS Exchange Message Format (details)
### TGS Exchange Message Format (details)
### AP Exchange Message Format (details)

Reader thinking: "I'm reading about AS-REQ format... wait, what was the purpose of AS Exchange again?" scrolls up

After (correct):

### AS Exchange: Get TGT with Password
  (flow diagram + message table)
  #### AS-REQ format
  #### AS-REP format

### TGS Exchange: Get Service Ticket with TGT
  (flow diagram + message table)
  #### TGS-REQ format
  #### TGS-REP format

### AP Exchange: Authenticate to Service
  (flow diagram + message table)
  #### AP-REQ format
  #### AP-REP format

Each section is self-contained. Reader can understand one phase completely before moving on.

When to Apply

• Protocol explanations (request/response pairs)
• Multi-step processes (each step = one section)
• API documentation (each endpoint = overview + examples + errors)

---

Part 3: Active Learning with Thought Questions

The Problem

Passive reading leads to shallow understanding. Readers may feel they understand while reading, but can't apply the knowledge later.

Symptoms:

• Reader finishes article but can't answer basic questions
• Confusion about similar concepts (e.g., "What's the difference between X and Y?")
• Misunderstanding edge cases or security implications

The Solution: Add Thought Questions

At the end of each major section, add questions that:

1. Target common confusion points
2. Let readers self-assess understanding
3. Use collapsible answers (<details>) for self-paced learning

Question Design Principles

Good questions target:

• Differences between similar concepts ("TGT vs Service Ticket")
• "Why" questions about design decisions ("Why not just send the password?")
• Security implications ("What if X is stolen?")
• Edge cases ("What if the attacker replays immediately?")

Bad questions:

• Recall questions with obvious answers ("What does KDC stand for?")
• Questions answered in the previous paragraph
• Questions requiring external knowledge

Format

#### 思考題

<details>
<summary>Q1：[Question that targets a common confusion point]</summary>

[Structured answer with examples if helpful]

</details>

<details>
<summary>Q2：[Question about design rationale or security]</summary>

[Answer explaining the "why"]

</details>

Example Questions by Topic

For authentication protocols:

• "Why can't the attacker use the stolen ticket/token?"
• "What's the difference between [credential A] and [credential B]?"
• "Why does [component X] need to exist? Can't we skip it?"

For encryption/security:

• "Why is [data] encrypted with [key A] instead of [key B]?"
• "What can an attacker do if they obtain [component X]?"
• "Why are there two encrypted parts in this message?"

For system design:

• "Why is this centralized/distributed?"
• "What are the tradeoffs of this design?"
• "What happens if [component] fails?"

Placement

Place thought questions at the end of each major section, not at the end of the article. This:

• Reinforces learning while context is fresh
• Breaks up long content into digestible chunks
• Gives natural pause points for readers

---

Part 4: Reader Review - Validate with a Naive Reader

The Problem

As the author, you're too close to the material. You understand the concepts deeply, which makes it hard to spot gaps in explanation that would confuse a newcomer.

Symptoms:

• Readers ask questions you thought were obvious
• Implicit assumptions that experts make but beginners don't share
• Logical jumps that feel natural to you but confuse others

The Solution: Spawn a Naive Reader Subagent

After completing your article, use the Task tool to spawn a subagent that role-plays as a reader who knows nothing about the topic. This reader will identify:

1. Unclear concepts - Terms or ideas that need more explanation
2. Missing context - Background knowledge the author assumed
3. Logical gaps - Steps or connections that aren't explicit

Workflow

After finishing the article:

1. Spawn a subagent with the "naive reader" prompt (see below)
2. The subagent reads the article and reports confusion points
3. For each confusion point, either:
   - Add clarification directly to the article
   - Add a thought question (思考題) to prompt deeper thinking
4. Repeat if major changes were made

Subagent Prompt Template

Use this prompt when spawning the reader review subagent:

You are a reader who knows NOTHING about [TOPIC]. You have general intelligence
but zero domain knowledge about this subject.

Read the following article and identify:
1. Terms or concepts that are used but not clearly explained
2. Logical jumps where you feel lost ("how did we get from A to B?")
3. Assumptions the author seems to make about your prior knowledge
4. Sections where you understand the words but not the meaning

For each issue, explain:
- Where in the article the confusion occurs
- What specifically is unclear
- What question you would ask the author

Be honest about confusion. Don't pretend to understand. If something feels
vague or hand-wavy, say so.

Article to review:
[PASTE ARTICLE CONTENT]

Handling Feedback

Feedback Type	Action
Missing definition	Add definition before first use
Unclear explanation	Expand with example or analogy
Logical gap	Add transitional explanation
Assumed knowledge	Add background section or link
Edge case question	Add as 思考題 with answer

Example

Subagent feedback:

"In the section about TGS Exchange, you mention 'session key' but I don't understand what makes it different from a regular encryption key or why it's called 'session' key."

Resolution options:

1. Add clarification:

   Session Key（會話金鑰）是一個臨時的加密金鑰，只在這次「會話」
   （session）期間有效。與長期金鑰不同，session key 用完即丟，
   降低了金鑰洩露的風險。
   

2. Add as thought question:

   <details>
   <summary>Q：為什麼要用 Session Key 而不是直接用長期金鑰？</summary>
   
   長期金鑰（如使用者密碼衍生的金鑰）如果頻繁使用，被竊取的風險較高。
   Session Key 是臨時產生的，即使被竊取也只影響單次會話，大幅降低安全風險。
   
   </details>
   

---

Part 5: Series Articles and Prerequisites

The Problem

When writing articles that are part of a series, readers may land on an advanced article without having read the prerequisites, leading to confusion.

Symptoms:

• Readers ask questions that were answered in previous articles
• Confusion about basic terminology that the series assumes known
• Readers struggle because they lack foundational knowledge

The Solution: Explicit Prerequisites Block

At the start of every series article, add a prerequisite notice:

:::note
**前置閱讀**

本文假設你已經讀過系列的前幾篇文章，特別是：
- [Previous Article Title](/posts/previous-article-slug)——理解 X 和 Y 概念

如果你不熟悉 Z，建議先閱讀上述文章。本文會使用「Term A」、「Term B」等術語。
:::

What to Include

1. Required reading: Link to essential previous articles
2. Key concepts: List what concepts are assumed known
3. Terminology warning: Mention specific terms that won't be re-explained

Example

From a FreeIPA certificate management article (part 4 of a Kerberos series):

:::note
**前置閱讀**

本文假設你已經讀過系列的前幾篇文章，特別是：
- [FreeIPA 實戰：部署企業級 Kerberos 環境](/posts/freeipa-kerberos-deployment)——理解 FreeIPA 架構和 Kerberos Principal

如果你不熟悉 Kerberos，建議先閱讀上述文章。本文會使用「Principal」、「keytab」等 Kerberos 術語。
:::

---

Part 6: Bilingual Terminology Handling

The Problem

When writing technical content in Chinese (or other non-English languages), mixing English technical terms with the local language can create readability issues if not done consistently.

Symptoms:

• Inconsistent use of English vs translated terms
• Poor readability due to missing spaces around English terms
• Reader confusion about whether two terms refer to the same concept

The Rule: Decide Early, Apply Consistently

Before writing, decide your terminology strategy:

Strategy	When to Use	Example
All Chinese	Audience prefers native terms	憑證、私鑰、公鑰
All English	Technical audience, industry standard terms	certificate, private key
Mixed (recommended)	Bilingual audience, core terms in English	Certificate 是一份「數位身份證」

Mixed Strategy Guidelines

For the mixed approach (English core terms, Chinese explanations):

1. First occurrence: **English Term**（中文解釋） or **English Term** 是...
2. Subsequent occurrences: Just the English term
3. Always add spaces around English terms in Chinese text

Spacing rules:

✅ 當你申請 certificate 時，CA 會驗證你的身份
❌ 當你申請certificate時，CA會驗證你的身份

✅ 這個 private key 必須保密
❌ 這個private key必須保密

Glossary Table

For articles with many technical terms, add a quick reference table early:

### 常見術語速查

| 術語 | 說明 |
|---|---|
| TLS | Transport Layer Security，HTTPS 使用的加密協議 |
| Private Key | 必須保密的密鑰，用於解密和簽章 |
| Public Key | 可公開的密鑰，用於加密和驗證簽章 |
| Certificate | 包含 public key 和身份資訊的數位文件 |
| CA | Certificate Authority，簽發 certificate 的機構 |

Example Progression

First mention (with explanation):

**Certificate** 是一份「數位身份證」，包含擁有者的身份資訊和 public key。

Subsequent mentions (term only):

當你連接到 HTTPS 網站時，伺服器會出示 certificate。

---

Part 7: Research Survey & Comparison Reports

The Problem

When synthesizing research from many sources (papers, docs, blog posts) into a technical report, the result often reads like a disorganized link dump or an overwhelming wall of text with no actionable takeaways.

Symptoms:

• Reader can't tell which sources matter most
• No clear recommendations or decision framework
• Comparison tables missing or inconsistent
• Actionable next steps buried in prose

The Rule: Structure for Decision-Making

A survey report should help the reader make decisions, not just absorb information. Every section should answer: "So what? What should I do with this?"

Recommended Report Structure

1. Research Scope        — What was surveyed, how many sources, what categories
2. Core Concepts         — Define the framework/taxonomy FIRST (define before use)
3. Comparison Tables     — Side-by-side tool/method comparisons
4. Detailed Analysis     — Deep dives grouped by theme, not by source
5. Recommended Workflows — Concrete step-by-step procedures
6. Curated Resources     — Top 10 (not top 100) with why each matters
7. Action Items          — Numbered, specific next steps for the reader

Comparison Table Design

Good comparison table:

| Tool | Tracing | Evaluation | Open Source | Best For |
|---|---|---|---|---|
| **LangSmith** | Best (LangChain native) | evaluate() API | No | LangChain ecosystem |
| **Langfuse** | Good (OTel) | DeepEval/RAGAS | Yes | Self-hosted, cost control |

Rules:

• Max 5-6 columns (more → unreadable)
• Bold the tool/method name in first column
• Include a "Best For" or "When to Use" column — this is the decision column
• Follow with a Recommendation Matrix mapping scenarios to choices:

| Scenario | Recommended Stack |
|---|---|
| LangChain ecosystem | **LangSmith** + OpenEvals |
| Self-hosted priority | **Langfuse** + DeepEval |

Curated Resource Lists

When selecting from many sources, apply the Top-N with justification pattern:

1. **"Paper Title"** — Author (Year)
   One-line summary of why this specific resource matters
   https://url

Rules:

• 10 resources is the sweet spot (not 3, not 50)
• Each entry needs a why it matters line, not just a summary
• Order by importance/relevance, not chronologically
• Group by theme if over 10 items

Workflow Documentation

When documenting recommended workflows, use the named workflow pattern:

### Workflow A: Golden Dataset Driven (recommended for starting)

Step 1 → Step 2 → Step 3

### Workflow B: Production Data Flywheel (recommended for mature systems)

Step 1 → Step 2 → Step 3

Rules:

• Give each workflow a short memorable name
• Add parenthetical guidance on when to use each
• Use ASCII flow diagrams for multi-step processes
• Include concrete code snippets where applicable

Threshold Tables

When reporting metrics or benchmarks, include production-ready thresholds:

| Metric | Description | Recommended | High-stakes Domain |
|---|---|---|---|
| **Faithfulness** | Grounded in context | > 0.85 | > 0.9 |
| **Relevance** | Answers the question | > 0.8 | > 0.85 |

This transforms abstract metrics into actionable standards.

Anti-patterns

1. Link dump: Listing 50+ URLs without curation or ranking
2. Source-organized: Grouping by "what Paper A says, what Paper B says" instead of by theme
3. Missing "so what": Detailed analysis with no recommendations
4. No comparison tables: Forcing readers to extract comparisons from prose
5. Buried action items: Next steps hidden in the middle of analysis

---

Part 8: Academic Paper Adaptation

The Problem

Rules for tutorials and technical articles do not transfer directly to academic papers. A tutorial can teach through analogies, thought questions, prerequisite blocks, and recommended workflows. A paper must instead defend a research claim through precise terms, ordered concepts, evidence, limitations, and citations.

When using this skill on a paper draft, the goal is not to make the paper more interactive. The goal is to make the argument readable and defensible.

What Does Not Belong In A Formal Paper

Do not add tutorial-only devices to the body of an academic paper:

• Thought questions: Do not add self-check questions or collapsible answers to a paper body. Use them only in study notes, teaching material, or reviewer preparation notes.
• Naive-reader feedback text: Use naive-reader review as a revision workflow, not as paper content.
• Series prerequisite blocks: Replace prerequisite notices with a short scope statement, assumed background, or terminology paragraph in the introduction or methodology.
• Pure teaching analogies: Use a short motivating example only when it supports the research problem. Do not build the paper around an analogy.
• Recommendation matrices and action items: In papers, convert these into limitations, future work, design implications, or evaluation criteria.
• Curated resource lists: Related work should synthesize research by theme or problem, not list resources by usefulness.
• Production-ready threshold tables: Use thresholds only when they are part of the evaluation design or are justified by prior work. Do not invent operational thresholds for rhetorical clarity.

What Transfers Well To Papers

The following rules apply strongly to academic writing:

• Define before use:
  • Define every core term before using it in claims, figures, tables, or evaluation.
  • For a systems paper, define objects such as event, attempt, template, group, lifecycle, rule, evidence, and outcome before using them in methodology or evaluation.
• Order concepts by dependency:
  • Introduce the problem domain before the data model.
  • Introduce observable evidence before parser output.
  • Introduce parser output before higher-level grouping.
  • Introduce grouping before lifecycle interpretation.
  • Introduce lifecycle and workflow before evaluation metrics.
• Avoid forward references:
  • Do not rely on phrases such as "explained later" when the current paragraph needs the concept.
  • Add a short local definition or move the concept earlier.
• Avoid circular definitions:
  • Do not define one paper object using another object that has not yet been defined.
  • If two objects depend on each other, first define the shared parent concept, then define each object separately.
• Keep claim and evidence close:
  • A claim should be followed nearby by its evidence, citation, table, figure, or explicit limitation.
  • Do not place all citations in a final source list while leaving key claims unsupported in the text.
• Group by logical unit:
  • Related work should be grouped by research problem, method family, or evidence role, not by one paragraph per paper.
  • Methodology should be grouped by data transformation stage, with input, output, assumptions, and failure modes close together.
  • Evaluation should be grouped by research question or claim, with metrics and limitations next to each claim.
• State what the paper does not prove:
  • If the evidence only supports a symptom, do not call it a root cause.
  • If the evaluation only reports aggregate replayability, do not claim user usefulness.
  • If a label requires human judgment, mark it as unverified until the paper has a labeled dataset.

Paper Draft Review Checklist

Use this checklist when reviewing a thesis chapter, conference paper, or journal manuscript:

• The introduction defines the problem before introducing the proposed object or method.
• Every research question has a matching claim, evidence source, and limitation.
• Core terms are defined before first argumentative use.
• Acronyms are expanded on first use unless they are universal in the target field.
• Related work is organized by theme or gap, not by source order.
• Each related-work section ends by explaining how that literature changes this paper's method, data boundary, claim boundary, or evaluation.
• Methodology states input, transformation, output, assumptions, and failure modes for each stage.
• Evaluation uses the same units defined in methodology and does not mix rows, events, attempts, documents, or users.
• Tables and figures appear near the claims they support.
• Limitations match actual missing evidence, not generic disclaimers.
• Future work contains only work that is outside the current evidence, implementation, or author decision boundary.

Thesis-Specific Pattern Learned From Use

When applying technical-writing rules to a research paper, first remove tutorial-only guidance, then keep the structural rules that protect the argument. In the mail-log thesis draft, the reusable pattern is:

problem framing
  -> observable evidence
  -> data preparation
  -> parser or template output
  -> higher-level grouping
  -> lifecycle or workflow interpretation
  -> evaluation claim
  -> explicit limitation

This pattern prevents common paper-draft failures:

• using a later concept before defining it;
• treating parser output as a final research object;
• presenting workflow support without evaluation evidence;
• calling an observable symptom a root cause;
• separating a claim from its table, figure, citation, or limitation.

---

Complete Checklist

When writing technical content:

Concept Ordering:

• List all technical terms before writing
• Map concept dependencies
• Keep analogies pure (no mixing with jargon)
• Define core concepts early in the article
• Add a mapping table if using analogies
• Review: every term usage comes after its definition

Section Structure:

• Group related content together (overview + details in same section)
• Each section is self-contained and can be understood independently
• Reader doesn't need to scroll back to understand current section

Active Learning:

• Add 2-4 thought questions at the end of each major section
• Questions target common confusion points, not recall
• Answers are in collapsible <details> blocks
• Questions cover "why" and "what if" scenarios

Reader Review:

• Spawn naive reader subagent after completing the article
• Address all confusion points identified
• Add clarifications or thought questions as appropriate
• Re-review if major changes were made

Series Articles:

• Add prerequisite notice at the start (:::note block)
• Link to required previous articles
• List assumed knowledge and terminology

Bilingual Terminology:

• Decide terminology strategy (Chinese/English/Mixed)
• First mention: term with explanation
• Subsequent mentions: term only
• Add spaces around English terms in Chinese text
• Consider adding a glossary table for many terms

Research Survey Reports:

• Start with research scope (sources count, categories)
• Define core taxonomy/framework before detailed analysis
• Group analysis by theme, not by source
• Include comparison tables with max 5-6 columns and a "Best For" column
• Add recommendation matrix mapping scenarios to choices
• Curate top ~10 resources with "why it matters" justification
• Name each recommended workflow and note when to use it
• Include production-ready threshold tables for metrics
• End with numbered, specific action items

Academic Papers:

• Remove tutorial-only devices from the paper body: thought questions, collapsible answers, prerequisite callouts, recommendation matrices, and action-item endings.
• Define every core term before first argumentative use.
• Introduce concepts in dependency order: problem -> evidence -> representation -> method -> workflow -> evaluation -> limitation.
• For every research question, identify the claim, evidence, and limitation.
• Keep each claim near the citation, table, figure, or result that supports it.
• Organize related work by theme, method family, or research gap.
• Keep methodology stages self-contained: input, output, assumption, and failure mode.
• Use consistent counting units across methodology and evaluation.
• State what the paper does not prove when the available evidence is incomplete.