Before & after rewrites
Editing is most of the job. Here are eight drafts of the kind I see every week, across API docs, help articles, product copy and communications, and what I’d ship instead. Toggle between versions, then open the notes to see the reasoning behind each change.
I wrote every “before” for this page as a realistic composite, so no real colleague’s draft appears here. The rules behind the edits come from the style guides I’ve worked with: house guides based on the Google developer documentation style guide and the Microsoft Writing Style Guide.
Developer documentation
An API parameter description
Parameter: reference
API reference · Audience: developers integrating payouts
- Concise
- Concrete values
- No filler phrases
reference (string): This field is used for the purpose of providing a reference which will be displayed. It should be noted that there is a maximum length restriction that is applicable to this field and if it is not provided then a default value will be utilized by the system.
reference (string, optional): Text the recipient sees on their bank or wallet statement. Up to 35 characters. Defaults to your business name.
What I changed and why (4)
- Put who sees it and where first. That’s the reason a developer would set this field.
- Replaced the vague “maximum length restriction” with the actual number: 35 characters.
- Stated the default outright instead of “a default value will be utilized by the system”.
- Removed filler: “for the purpose of”, “it should be noted that”, “utilized”. Simple words beat complex ones: use, not utilize.
An error message
Error: expired quote
API and in-product error · Audience: developers and end users
- Effect → cause → solution
- Don’t blame the user
- Plain language
Error 400: You submitted an invalid quote state. Please contact support if the issue persists.
Quote expired: Quotes lock the exchange rate for 60 seconds, and this one is older than that. Create a new quote, then send the payout straight away.
What I changed and why (4)
- Follows the effect → cause → solution pattern: what happened, why, and what to do.
- Removed the blame. “You submitted an invalid…” makes the reader feel at fault for something the system did (the quote timed out).
- Named the cause in plain words. “Invalid quote state” makes the reader guess.
- Ended with a self-service fix instead of sending people to support.
Help documentation
A help article opening
Help article: adding users
Help center · Audience: workspace admins
- Gerund, sentence-case title
- Context first
- Bold UI labels
- Descriptive links
- Location before action
How To Add Users To Your Workspace?
In order to add users, please note that you need to be an admin. Click on the “Add User” button which you can find in the Users tab of Admin Settings and then enter the e-mail ID of the user(s), etc. To learn more about roles, click here.
Adding users to your workspace
Invite teammates so they can view and edit items in your workspace. Only workspace admins can add users.
- Go to Admin settings > Users.
- Click Add users.
- Enter one or more email addresses, and then click Send invites.
New users get the Member role by default. You can change it anytime from user roles and permissions.
What I changed and why (6)
- Titles aren’t questions. “How to…?” is an indirect question, so I used a gerund title in sentence case that matches how people search.
- Opened with a short context paragraph: what the feature does and who can use it, before the first step.
- Put the location before the action (“Go to Admin settings > Users”), in the order the reader moves through the product.
- Formatted UI labels in bold with the product’s own casing, not in quotation marks. “Click”, not “click on”.
- Used “email address”, not “e-mail ID”, and dropped “user(s)” and “etc.”
- Replaced “click here” with descriptive link text. It tells readers where they’re going and works for screen readers.
An onboarding step
Participant portal: configure settlement
Admin guide · Audience: operations admins at a participant company
- Numbered steps
- Prerequisites first
- Specific expectations
In order to be able to configure your settlement account, you will first need to make sure that you have navigated to the Settings area, where you should be able to find the Settlement tab, and once you are there you can click on the Add Account button and enter all the details that are required, after which the account will need to be verified before it becomes active, which may take some time.
Before you begin: you need the Admin role.
- Go to Settings > Settlement.
- Click Add account.
- Enter your bank’s SWIFT/BIC code and account number, and then click Save.
We verify the account within two business days and email you when it’s active. Settlements can’t start until then.
What I changed and why (4)
- Broke one 70-word sentence into numbered steps, each starting with a verb, because people follow procedures one action at a time.
- Moved the prerequisite (Admin role) to the top so nobody gets stuck at step 2.
- Replaced “all the details that are required” with the actual fields.
- Turned “may take some time” into a real expectation: two business days, with an email. (In real docs, I’d confirm that number with the ops team first.)
Product copy
Microcopy in a settings form
Settings form: labels, buttons and messages
In-product UI text · Audience: every user
- Placeholders add guidance
- Verb-first buttons
- No “(s)”
- Punctuate sentences only
- Label
- Workspace URL
- Placeholder
- Enter workspace URL
- Button
- Click Here To Save
- Error toast
- Error!! You uploaded an invalid file
- Success toast
- 1 user(s) deleted successfully.
- Label
- Workspace URL
- Placeholder
- acme-finance
- Help text
- Use lowercase letters, numbers, and hyphens.
- Button
- Save changes
- Error toast
- Upload failed: This file format isn’t supported. Upload a CSV or XLSX file.
- Success toast
- 1 user deleted · 10 users deleted
What I changed and why (5)
- The placeholder repeated the label. Now it shows a sample value, and a help text explains the format. Sample values aren’t punctuated. Full sentences are.
- Buttons start with a verb in sentence case and say what happens. “Click here” describes the mouse, not the action.
- The error follows effect → cause → solution, without exclamation marks or blaming the user.
- Dropped “(s)”. I’d ask engineering to handle singular and plural in code, so the reader always sees correct grammar.
- Removed “successfully”. The toast already says it worked.
Sentence-level polish
Pricing note: approvers
Help center · Audience: account admins
- Second person
- Number style
- No Latin abbreviations
- Simple tense
The admin can easily add upto 5 approvers per step, i.e. a total of 25 approvers across the workflow, and approvers are being charged at USD $2 each which is a 20 percentage discount.
You can add up to five approvers to each step, and up to 25 across the workflow. Each approver costs 2 USD, a 20 percent discount.
What I changed and why (5)
- Switched to second person. The reader is the admin, so talk to them directly.
- Removed “easily”. If it isn’t easy for this reader, the word makes them feel worse.
- Number style: spell out zero to nine, use numerals for 10 and above, and write “up to” as two words.
- Replaced “i.e.” with plain English, and put the currency code after the number: 2 USD, not “USD $2”.
- Used “percent”, not “percentage”, and the simple present (“costs”) instead of the progressive (“are being charged”).
Communications
A pre-release note
Pre-release note: scheduled exports
Release communication · Audience: customers and admins
- What’s new vs. what’s now
- Availability
- Call to action
- No hype
Exciting News!!! 🚀
We are super thrilled to announce that our amazing new exports experience is finally going to be here very soon! It is going to be revolutionizing the way reports are being shared by teams everywhere. It will be available for some customers in the near future. Stay tuned!!
Coming soon: scheduled report exports
Until now, you exported reports by hand. Soon, you can schedule reports to arrive in your team’s inbox automatically.
What’s new
- Schedules: Send any report daily, weekly, or monthly.
- Formats: Choose CSV or XLSX.
- Recipients: Add up to 20 email addresses to each schedule.
Availability: Rolling out to all Enterprise plans in the first week of March 2027.
Questions or feedback? Contact your account manager.
What I changed and why (5)
- The title says what is coming, not how excited we are.
- The summary contrasts what’s now with what’s new in one sentence each.
- Turned “revolutionizing the way…” into specific capabilities in a scannable list with bold labels.
- Replaced “some customers in the near future” with who and when. Vague availability creates support tickets.
- Ended with a clear call to action, and cut the exclamation marks and emoji.
A partner email
Partner notice: API version deprecation
Partner communication · Audience: technical and business contacts at a participant
- Lead with impact
- Specific dates
- Clear next step
Dear Partner,
We would like to take this opportunity to inform you that as part of our ongoing commitment to continuously improving our platform and services, we have made the decision to deprecate version 1 of our Payouts API at some point in the upcoming quarter. We kindly request that you take the necessary steps to migrate. Please reach out with any questions.
Hello,
Payouts API v1 stops working on March 31, 2027. To keep sending payouts after that date, move to v2 before then.
Most integrations need three changes, listed in the v2 migration guide. Your sandbox already supports v2, so you can test today.
If you need more time, reply to this email by January 31, and we’ll work out a plan with you.
What I changed and why (5)
- Lead with the impact and the date. Busy readers might read only one sentence, so make it this one.
- Replaced “at some point in the upcoming quarter” with a specific date. You can’t plan a migration around a vague date.
- Cut the corporate opener. It said nothing the reader needed.
- Gave a next step (the guide), a way to start now (the sandbox), and a clear path if they can’t meet the deadline.
- In real partner emails, this version would then go through Legal and Compliance review. Clear drafts make those reviews faster, too.
Thanks! Every doc I ship gets better with feedback, including this one.