Technical Writing Examples: 7 Before-and-After Rewrites
Most advice about technical writing stays abstract: be clear, be concise, know your audience. That is true, but it is hard to act on. It is much easier to improve your own docs when you can see a weak passage next to a stronger one and understand exactly what changed.
This guide gives you seven technical writing examples, each shown before and after a rewrite. They cover the documents most teams actually write: instructions, user manual sections, troubleshooting help, FAQ answers, release notes, procedures, and headings. After each example, you will find the rule behind the fix, so you can apply it to your own content. Every technical writing sample here uses a made-up product, so the details (file limits, prices, menu names) are only illustrations.
What counts as technical writing?
Technical writing is writing that helps someone understand or do something specific, such as setting up a product, fixing a problem, or following a process. The U.S. Bureau of Labor Statistics describes technical writers as people who prepare instruction manuals, how-to guides, and other supporting documents, including assembly instructions and FAQ pages.
You don't need the job title to do this work. Support agents write help articles. Product managers write release notes. Operations leads write procedures. If your reader needs to act on what you wrote, you are doing technical writing.
Why examples beat rules
Good technical writing is judged by what readers do with it, and most readers don't read closely. In a well-known Nielsen Norman Group study, 79% of test users scanned any new page they came across, and only 16% read word by word. The same research found that a version of a page that was concise, scannable, and objective scored 124% higher in measured usability than the original promotional version.
Concise, scannable, and objective are the three ideas running through every example below.
1. Step-by-step instructions
Before
To get started with exporting, you'll first want to make sure you are on the Reports page, and then you can click the Export button which is located at the top right, after which a dialog will open where you should simply choose a format and then press Save.
After
To export a report, follow these steps:
- Go to the Reports page.
- Click Export.
- Select a file format.
- Click Save. The file downloads to your computer.
What changed: The "after" version puts one action in each numbered step and starts every step with a verb. It states the goal first ("To export a report"), and it tells the reader what happens after the last step. These are core rules in Google's developer documentation style guide, which also advises against words like "simply" and "easy" in procedures. A step only feels simple to someone who already knows how to do it.
2. A user manual example: the overview section
Before
Our revolutionary Dashboard module is a powerful, intuitive hub that empowers teams to unlock insights like never before, seamlessly bringing together everything you need in one place.
After
The Dashboard shows your team's open tasks, overdue items, and recent activity on one page. Use it to see what needs attention today. You can add, remove, and rearrange the cards on it.
What changed: The first version is marketing copy that ended up in a manual. It contains adjectives but no information. The rewrite answers the three questions a manual overview should answer: what this is, what it's for, and what you can do with it. The Nielsen Norman Group research found that promotional language makes readers work harder, because they have to filter out hype to find the facts. Objective writing removes that burden.
3. Troubleshooting and error messages
Before
Error: Operation failed. Please try again later or contact your administrator.
After
Your file wasn't uploaded because it's larger than 25 MB. Compress the file or split it into smaller files, and then upload it again.
What changed: Google's technical writing course on error messages says a good message answers two questions: what went wrong, and how does the user fix it. The "before" message answers neither. It also sends the reader to someone else, which creates a support ticket that the message itself could have prevented. Use the same pattern in troubleshooting articles: name the cause, then give the fix.
4. FAQ answers
Before
Q: Can I change my plan?
A: Great question! Plans are a really important part of how our service works, and we know that needs change over time. There are several options available depending on your situation, which we'll walk through below.
After
Q: Can I change my plan?
A: Yes. Go to Settings > Billing and click Change plan. The new plan starts right away.
What changed: The answer comes first. Readers who scan FAQ pages look for the yes or no, then the next action. Everything else in the "before" version is warm-up. Google's guidance on voice and tone suggests a friendly, conversational style, but it also warns against filler and exclamation points. Friendly doesn't mean long.
5. Release notes
Before
Version 4.2 includes various improvements and bug fixes, along with enhanced performance and a number of UI updates.
After
Version 4.2
- New: You can now schedule reports to send by email every week.
- Improved: Search results now include archived projects.
- Fixed: Dates in exported files now match your time zone setting.
What changed: "Various improvements" tells readers nothing, so they can't decide whether the update matters to them. The rewrite labels each change, describes it from the user's point of view ("you can now…"), and keeps each item to one line. A reader who scans only the bold labels still learns what kind of release this is.
6. Procedures and SOPs
Before
The refund should be approved by a manager if it's over the limit, and once that's done the agent processes it in the billing system and the customer gets notified, unless it was a duplicate charge, in which case finance handles it.
After
Who: Support agent
- If the charge is a duplicate, send the request to Finance and stop here.
- If the refund is over $200, ask a manager to approve it.
- In the billing system, process the refund.
- Send the customer the refund confirmation email.
What changed: The "before" version hides the order of steps, who owns each one, and the exceptions in a single sentence. The rewrite names the role at the top, handles the exception first so nobody does unnecessary work, and puts each condition before the action it controls ("If the refund is over $200, ask…"). Readers need to know whether a step applies to them before they start it.
7. Headings readers can scan
Before
- Some Information About Getting Your Account Set Up
- Things to Know Regarding Notifications
- A Few Words on Permissions
After
- Set up your account
- Turn notifications on or off
- Give teammates access
What changed: Nielsen Norman Group's eye-tracking research shows that readers often scan in an F-shaped pattern, focusing on the first words of each line. They first described the pattern in 2006 and confirmed it on desktop and mobile in 2017. Their advice: start headings with the most informative words, so a reader who sees only the first two words still gets the point. The "before" headings spend those words on "Some Information" and "Things to Know." The "after" headings start with the task.
Technical writing best practices these examples share
Put the seven rewrites side by side and the same few habits show up:
- Lead with what the reader needs. Put the answer, the goal, or the task first.
- Use one idea per unit. One action per step, one change per release note line, one topic per heading.
- Put conditions before actions. Readers should know whether a step applies before they do it.
- Replace adjectives with facts. "Shows open tasks and overdue items" beats "powerful hub."
- Say what happens next. Tell readers the result of the last step or how to fix the error.
- Cut filler. "Please note," "simply," and "great question" add words without adding help.
These habits work across all types of technical writing, from a one-line error message to a full manual.
How to write technical documentation your team can reuse
Examples are most useful when they become your team's defaults. A few practical ways to make that happen:
- Turn the "after" versions into templates. Create a procedure template, a release note template, and an FAQ template so writers start from a good structure instead of a blank page. In Sonat, you can save these as templates and reuse them across manuals.
- Keep a short internal example library. One page of before-and-after pairs from your own docs teaches new writers faster than a long rulebook. For more on wording, see our guide to plain language in technical writing.
- Review against the examples. When someone reviews a draft, they can point to the matching example instead of debating style. Sonat's review and approval workflows let a second person check a topic before it goes live.
- Check readability before you publish. A readability check flags long sentences and dense paragraphs automatically. Here is what a readability score means for your documentation.
- Learn from readers. Feedback on each published topic shows you which pages still confuse people, so you know which ones to rewrite next.
Conclusion
The best technical writing examples aren't impressive. They are short, specific, and easy to act on. Each rewrite above follows the same idea: work out what the reader is trying to do, then remove everything that slows them down.
Pick one page from your own documentation this week, such as a procedure, an FAQ, or an error message, and rewrite it using the matching example. Then make that version your template. If you want one place to write, review, and publish documentation like this, you can start with Sonat for free.