技術寫作示例：定義、警告、設定文件與程式碼註解

Technical writing isn't only long manuals. Most of it is small. A one line definition in a glossary. A warning box above a dangerous command. A description beside a config option. A comment above a tricky loop. These bits get read at the exact moment someone is about to make a mistake, so the wording matters more than its length suggests.

This post collects annotated technical writing examples from the small places in docs and code. Each one shows a weak version, a stronger version and the reason the stronger one works. I've left out READMEs, error messages and endpoint reference pages, since those have their own guides.

1. A definition

Weak.

A tenant is a logical isolation boundary within the multi-tenant architecture.

Strong.

A tenant is one customer's space in the app. Each tenant has its own users, data and settings, and nothing in one tenant is visible from another.

The weak version defines the word with harder words. The strong one says what it is, what it contains and the rule that matters. Good definitions answer "what is it" and "why do I care" in two sentences.

2. A warning

Weak.

Note. Be careful when running this command.

Strong.

Warning. db reset deletes every table in the target database. Run it against staging only, and check the DATABASE_URL value first.

"Be careful" gives the reader nothing to be careful about. A warning should name the consequence, the safe case and one concrete check. If you can't name the consequence, it probably isn't a warning.

3. A config option

Weak.

Strong.

A description that repeats the option name is a missed chance. Say what it controls, the default and what the edge values do.

4. A code comment

Weak.

# loop through items
for item in items:
    if item.qty > 0 and not item.hold:
        ship(item)

Strong.

# Items on hold are waiting for a fraud review, so we skip them
# even when they're in stock. They ship in the nightly batch instead.
for item in items:
    if item.qty > 0 and not item.hold:
        ship(item)

The code already says what it does. A comment should say why, especially when the why lives in another team's head.

5. A concept overview

Weak.

The system leverages an event-driven paradigm wherein state transitions are propagated asynchronously via a message broker to downstream consumers.

Strong.

When an order changes status, the order service publishes an event. Other services, like billing and email, listen for those events and react on their own schedule. The order service doesn't wait for them.

Swap abstract nouns for actors and actions. "Leverages an event-driven paradigm" becomes "publishes an event," and the reader can picture it.

Concept paragraphs are where most rewording happens. The facts are right, the order is wrong, and the vocabulary is borrowed from a whiteboard. Learning to reword a paragraph and keep its meaning is the core skill here, because a clearer version that drops a fact is worse than the dense one.

6. A migration note

Weak.

Version 4 introduces breaking changes to the auth module. Please update accordingly.

Strong.

Version 4 renames login() to signIn() and removes the remember flag. To upgrade, rename the call and move remember to the session options. Apps that skip this step will fail to compile.

"Update accordingly" pushes all the work onto the reader. The strong version lists what changed, what to do and what happens if they don't.

7. A troubleshooting entry

Weak.

If sync isn't working, try restarting.

Strong.

Sync shows "pending" for more than ten minutes. This usually means the device token expired. Sign out and back in on that device. If it still shows pending, send us the sync ID from Settings and we'll check the server side.

A troubleshooting entry needs a symptom as the heading, a likely cause, one fix and a next step if the fix fails.

Patterns across all seven

Looking at them together, the same moves keep showing up.

• Name the thing. Commands, options, values and versions by their real names.
• State the consequence. What happens if the reader does or doesn't act.
• Prefer actors and verbs. "The service publishes" beats "publication occurs."
• Give one next step. A reader who finishes a passage should know what to do.
• Keep the facts fixed. Rewording changes sentences, never defaults, limits or names.

Practicing on your own docs

Pick one page and look only at its definitions and warnings. They're short, so you can fix a dozen in an afternoon. Then move to concept paragraphs, which take longer but pay off most.

If a concept paragraph keeps defeating you, put it through Rephrase AI and read the alternative aloud next to your draft, while you hold every option name, version number and default value fixed as the spec says.