To update terminology across a whole documentation folder, build a list of every old term and its replacement, including plurals, capitalized forms and phrases that contain the term, then run all the replacements in one pass over the docs files with case-sensitive, whole-word rules. Put longer phrases before the shorter terms they contain, review the matches in a preview so code samples, URLs and historical notes are left alone, and search again afterwards for any old term that survived. Markdown, HTML, text and similar files can be changed this way in minutes; Word documents need Word's own Replace.
This guide walks through building the term list, handling the tricky forms, protecting the parts that must not change, and checking the result.
Step 1: build the term list
A product rename looks like one change, but it is usually ten. Start by searching the docs for the old name and noting every form it takes. A rename from Widget to Gadget might need:
| Old | New | Notes |
|---|---|---|
| Widget Pro | Gadget Plus | Longer phrase: must run first |
| Widget Cloud | Gadget Online | Longer phrase: must run first |
| Widgets | Gadgets | Plural |
| Widget | Gadget | Main term |
| widget | gadget | Lowercase, when used as a common noun |
| WIDGET | GADGET | Headings or labels in capitals |
| a Widget | a Gadget | Only matters if the article changes, as in a to an |
Keep this list in a spreadsheet with two columns, old and new. It becomes the record of the change, it is easy for a colleague to review, and it can be imported straight into a batch tool. Our guide to bulk find and replace from a CSV list covers the file format.
Step 2: get the order and options right
Longer phrases first
Rules run in order. If Widget to Gadget runs first, Widget Pro becomes Gadget Pro, and the later rule for Widget Pro never matches. Sort the list so phrases come before the single words inside them.
Case-sensitive, whole-word
Turn on match case so each capitalization is handled by its own rule. Turn on whole word so Widget does not match inside WidgetFactory or Widgetized. See case-sensitive find and replace across multiple files for the details.
Plurals in one rule
With regex, the singular and plural can share a rule: find \bWidget(s?)\b and replace with Gadget$1. The group captures the optional s and puts it back. Possessives are handled automatically: Widget's becomes Gadget's, because the apostrophe is a word boundary.
Articles: a and an
If the new name starts with a vowel sound, a Widget must become an Omni. Add a rule before the main one: find \b([Aa]) Widget\b and replace with $1n Omni, which handles both a and A at the start of a sentence.
Step 3: protect what must not change
Documentation mixes prose with things that look like prose but are not:
- Code samples.
widget.init()is an API name. If the code has not been renamed, the docs must keep the old name. Untick these matches in the preview, or keep code samples in separate files that you exclude. - URLs and anchors. Links such as /docs/widget-setup/ point to real pages. Changing the link text is fine; changing the URL breaks it unless the page is renamed too.
- Image and file names. widget-dashboard.png is a file on disk. Either rename the files and update references together, or leave both alone.
- Release notes and changelogs. "Widget 2.0 added export" is a historical fact. Exclude these files by name.
- Quotes and legal text. Trademark notices, license text and customer quotes should not be edited by a global rule.
Folder and extension filters handle most of this. For example, include *.md and *.html, and exclude the changelog folder and any *.json API reference files. The guide to limiting find and replace to specific file types and folders shows the filter syntax for common tools.
Step 4: run it with a preview
- Commit the docs, or copy the folder.
- Load the term list as rules, in order, each case-sensitive and whole word (or regex where noted).
- Run a preview and scan the changed lines. Look for code, URLs and file names among the matches, and untick them.
- Apply the changes.
- Build the docs site, if you have one, and check for broken links or images.
Bulk Replace is designed for this kind of glossary migration: keep the renames in a spreadsheet, import them as a CSV rule set, and sweep the whole docs folder in one pass. The before/after diff lets you untick matches inside code samples, every run is backed up for one-click undo, and the timestamped report lists each file changed with its match count, which is useful when a reviewer asks what the rename touched.
Step 5: check for survivors
After the run, search the docs for the old name with match case off and whole word off. Anything that remains should be something you chose to keep. Common survivors:
- Hyphenated or joined forms: Widget-based, WidgetHub.
- Unusual capitalization: WIDGET in a table header that no rule covered.
- Text split across lines: in Markdown, Widget at the end of one line and Pro at the start of the next. Search for
Widget\s+Prowith regex to catch those. - Alt text and titles: attribute values in HTML that are easy to overlook in a rendered preview.
Also search for the new term with a sanity check in mind, for example Gadget Gadget or an Gadget, which show that two rules overlapped.
What about Word and PDF documents?
Word .docx files are compressed packages, not plain text, so text-level batch tools skip them, and PDF files are not meant to be edited this way at all. For Word, open each document and use Replace (Ctrl+H) with Match case and Find whole words only ticked, or use a tool built specifically for Office files. For PDFs, edit the source document and export again. If your docs are mainly in Markdown or HTML, which is common for help sites, the whole job can be done in one pass.
Keep the glossary current
A terminology change is rarely the last one. Keep the term list next to the docs, add a line each time something is renamed, and you will be able to rerun the same list against new pages later. In Bulk Replace, saving the folder, filters and rules as a named project makes that a two-click job.
Frequently asked questions
How do I handle plurals and different capitalization?
Add a case-sensitive rule for each form, such as Widget to Gadget and widget to gadget. With regex, \bWidget(s?)\b replaced with Gadget$1 handles the singular and plural in one rule.
Does this work for Word documents?
Text batch tools work on Markdown, HTML, text and similar files. Word .docx files need Word's own Replace or a tool built for Office files.
How do I avoid changing code samples in the docs?
Review the preview and untick matches inside code blocks, or run the term change on prose files only with an extension filter.
