Technical Writing Examples: 8 Document Types With Before-and-After Rewrites

Technical writing is writing that helps someone do something or understand something specific: install software, follow a procedure, fix an error, use an API, operate a machine safely. Its examples are everywhere and mostly invisible when they work. You notice the instructions only when step 4 refers to a button that doesn’t exist.

This page collects examples across the document types technical writers produce most often. Every example below is illustrative, written for this article, and each comes with a weak version, an improved version and a short explanation of what changed. Seeing the edit is more useful than seeing only a polished result.

What the good examples have in common

Before the examples, the principles they apply. Two public style guides are worth reading in full. Google’s developer documentation style guide highlights include: “Use active voice: make clear who’s performing the action”, “Use second person: ‘you’ rather than ‘we’”, “Put conditions before instructions, not after” and “Use numbered lists for sequences.” The guide also says it “contains guidelines, not rules”, which is the right attitude for any style guide.

The Diátaxis framework splits documentation into four forms: tutorials, how-to guides, technical reference and explanation. Most confusing documents are two or three of these mixed together. A procedure interrupted by three paragraphs of background is a how-to guide with an explanation stuffed inside it.

With those in mind, here are the examples.

1. Step-by-step procedure

Weak:

To set up two-factor authentication, you should first go to your settings, and from there you can find the security section where there’s an option for 2FA which you’ll want to enable, after which a QR code is displayed that should be scanned using an authenticator app. Make sure you have an authenticator app installed before you begin.

Improved:

Before you begin, install an authenticator app on your phone.

1. Click your profile picture, then click Settings.
2. Click Security.
3. Under Two-factor authentication, click Turn on.
4. Scan the QR code with your authenticator app.
5. Enter the six-digit code the app shows, then click Verify.

What changed: the prerequisite moved to the top, where it prevents a dead end at step 4. One action per step. The interface labels are bold and match the screen exactly. The final step tells the reader how they know it worked.

2. API reference entry

Weak:

This endpoint is used to get users. You can pass various parameters to filter the results. It returns user data.

Improved:

GET /users

Returns a paginated list of users in the workspace, newest first.

Parameter	Type	Required	Description
status	string	No	Filter by active or suspended.
limit	integer	No	Results per page, 1 to 100. Defaults to 20.
cursor	string	No	The next_cursor value from a previous response.

Returns 403 if the API key doesn’t have the users:read scope.

What changed: reference documentation is for looking things up, so it should be consistent and complete rather than readable as prose. Every parameter has a type, whether it’s required, allowed values and a default. The likely error is documented next to the endpoint, not on a separate page.

3. Troubleshooting entry

Weak:

If you are having issues with syncing, there could be a number of causes. Try checking your connection and settings. If problems persist, contact support.

Improved:

Problem: Files stay in the “Waiting to sync” state.

Cause: The desktop app is paused, or the file is open in another program.

Fix:

1. Click the sync icon in the menu bar. If it shows Paused, click Resume.
2. Close the file in any program that has it open.
3. If the file still doesn’t sync after a few minutes, right-click it and choose Sync now.

What changed: the entry starts from the symptom the reader actually sees, in their words. It names a specific cause and a specific fix. “Contact support” is a last resort, not the main advice.

4. Release notes

Weak:

Version 4.2 includes various improvements and bug fixes to enhance your experience.

Improved:

Version 4.2

New: You can export reports as CSV from the Reports page.

Changed: Invoices now show the customer’s tax ID if one is saved on their account.

Fixed: Scheduled reports no longer send twice when the schedule is edited.

Action needed: The /v1/export endpoint will be removed in version 5.0. Use /v2/export instead.

What changed: grouped by what the reader needs to do with the information. The breaking change is labelled so nobody misses it. “Various improvements” tells the reader nothing; if a change is too small to describe, leave it out.

5. Error message

Weak:

Error 0x80041: Operation failed.

Improved:

Couldn’t save the file because the disk is full. Free up some space, then try again.

What changed: a useful error message says what happened, why, and what to do next. Keep the code in logs or in a “details” view for support staff, not as the whole message.

6. Safety warning in a manual

Weak:

Note: it is recommended that the power be disconnected prior to the removal of the cover in order to avoid the risk of electric shock.

Improved:

Warning: Unplug the power cord before you remove the cover. The power supply carries a dangerous voltage even when the switch is off.

What changed: the hazard is labelled and comes before the action. “It is recommended” became an instruction. The reason is concrete, which makes people more likely to follow it. For regulated products, the exact format of warnings may be set by a standard, so check which one applies before you rewrite.

7. Conceptual explanation

Weak:

Caching is a very important concept that allows for improved performance in many different scenarios by storing data.

Improved:

When the app loads your dashboard, it asks the server for the latest numbers. That request takes time. A cache keeps a copy of the response for a short period, so if you open the dashboard again a minute later, the app shows the saved copy instead of asking again. The trade-off: the numbers can be up to five minutes old. Click Refresh to fetch the latest data.

What changed: explanation is where context belongs, and the best explanations use the reader’s situation rather than a textbook definition. The improved version includes the trade-off, which is usually what generates support tickets.

8. Standard operating procedure

Weak:

All refunds should be processed according to policy and logged appropriately once they have been approved by the relevant person.

Improved:

Purpose: Refund a customer payment.

Who does this: Support agents. Refunds over $500 need approval from a team lead first.

1. Open the customer’s account and find the payment under Billing.
2. Click Refund and select a reason from the list.
3. Paste the ticket link into the Notes field.
4. Click Confirm. The customer receives an automatic email.

What changed: “the relevant person” and “appropriately” were placeholders for decisions nobody had written down. The improved version names the role, the threshold and where the record lives. Writing an SOP often exposes that the process itself was undefined.

Patterns across all eight

Looking at the rewrites together, the same edits recur:

• Put what the reader needs first. Prerequisites before steps, warnings before actions, the symptom before the cause.
• One idea per sentence, one action per step.
• Name things exactly as they appear. Interface labels, parameter names and error text should match what the reader sees.
• Replace vague words with decisions. “Appropriately”, “various”, “relevant” and “as needed” usually hide a missing fact.
• Say what success looks like. The last step of a procedure should tell the reader how they know it worked.
• Separate document types. If you’re explaining in the middle of a procedure, move the explanation to its own section and link to it.

What most people get wrong

The usual advice is “keep it simple”. That’s not quite right. Technical writing should be as simple as the reader’s task allows, and no simpler. A reference table that leaves out the default value or the error codes is simple and incomplete, and the reader has to go elsewhere. The goal is complete and easy to scan, which sometimes means a longer page with a better structure, not a shorter one.

The other common mistake is writing from the product’s structure instead of the reader’s task. Documentation organised by menu (“The Settings page”, “The Reports page”) is easy to write and hard to use. Documentation organised by task (“Export a report”, “Change who can see a report”) matches how people search.

Using these examples with AI

AI writing tools can produce a first draft of most of these document types, but they can’t know your product’s actual labels, limits or edge cases. Give the tool the facts (the real steps, the real parameter list, the real error) and ask it to apply the patterns above, then check every detail against the product. Our guide to technical writing with AI covers that workflow, and content for developers covers writing for technical audiences more broadly. For general readability checks, see our content readability tips.

A short checklist for any technical document

• Does the reader know what this page is for within the first two lines?
• Are prerequisites and warnings placed before the steps they apply to?
• Is every sequence a numbered list with one action per step?
• Do labels, names and messages match the product exactly?
• Is every vague word replaced with a specific value, role or condition?
• Does the reader know what success looks like?
• Has someone who didn’t write it followed it from start to finish?