The problem with names
There are only two hard things in Computer Science: cache invalidation and naming things.
Naming things is hard, and many people struggle to find good names for things. Technical writers often complain that we’d love to be involved in this process, or to push back from when the organisation decides to use names which are inaccurate, overloaded with multiple meanings in different contexts, hard to remember or type, or occasionally, just in poor taste.
Getting a seat at the table where names are chosen is a hard organisational problem that’s outside the scope of this book.
Renaming things
Unfortunately, precisely because naming things is hard, it often happens that the company decides to rename them later. From key concepts to names of products, this can be a significant lift for the whole business, with marketing pages, developer repos, training courses all needing to be corrected.
The product documentation is perhaps one of the thorniest of these, for a few reasons:
-
Unlike Marketing or training content, which can often focus exclusively on the latest version of products, your Docs site may support many old versions of content, all of which need to be updated.
-
In a Developer repo, there’s often a distinction between the "marketing name" and the "technical name" of things, for good reasons like backwards compatibility. Renaming here can be done on an "eventually consistent" basis, with both old and new names existing in different contexts. This is a wart, certainly, but may be an acceptable one.
-
Docs have to be pragmatic about mentioning the old name, in discoverable ways. Marketing may not want to see the old name ever. But customers who need support for their legacy version of a product will be confused if it’s not mentioned. The presence of a phrase like "Foo (formerly known as Bar)" in your docs will also be picked up by Search engines and LLMs alike.
-
Related: do we want to rename the product even in older versions of the docs? It might be reasonable to only rename the latest version of a product. Or product management might insist on doing so for all supported versions. In some cases, there are versions which are "not supported as such, but are still on the docs site" - it might be justifiable to not do a full renaming but to use admonition banners judiciously.
Find and Replace
If it receives over 100 points of dawizard in one turn, the cube is destroyed.
An editor of this 1994 Dungeons of Dragons book was instructed to replace all instances of the word "mage" with "wizard". The magic of Find and Replace, present in all text editors, is full of traps for the unwary.
-
we need to find all instances of the old name
-
NOT including words that simply contain that word
-
but including plurals, possessives, and other similar grammatical forms
-
searching for typos / variant capitalisations
-
NOT instances we want to leave unchanged ("formerly known as Foo")
-
NOT references to code/API structures or UI text that has not yet been renamed
-
NOT references to URLs or Antora xrefs that haven’t yet been changed
-
(however in the case of the latter, we should consider renaming those pages as part of this push.)
We may also need to consider grammatical elements.
In English, the a/an distinction is the most common example:
-
"An AcornRunner instance" → "A SquirrelRunner instance"
Other more exotic scenarios sometimes occur.
-
If the new name is stylised with an initial lowercase letter, we might prefer to avoid using it as the first word in a sentence.
-
A product name might lose it’s preceeding article (as Apple likes to refer to "iPhone" and "iPad" in marketing materials), requiring rewrites.
It’s important to understand your language, your style guide, and these issues before attempting any renaming!
It’s also important to understand timing. A renaming may be required to go at a particular date, to coordinate with other parts of the company (marketing, training, etc.)
If your writing team is still writing content with the old name until the changeover, you may have a lot of time to prepare, but very little time to execute the change.
Broadly speaking, the options are:
-
Manual find-and-replace in a text editor. The easiest conceptually, and may be suitable for smaller projects, or writers who don’t have dedicated tooling support.
-
Scripting. Code up the rules, run your script, and check the diff. Check which errors have been introduced. Request code-review. Update the script, and re-run (from the current state of your branch), rinse and repeat. At the final moment, run the rename again.
-
Ask an LLM. An LLM will likely do an unreasonably good job of this, and may correctly identify many of the edge cases we already looked at. Even so, you will want to do due-diligence, to be able to answer its clarifying questions. As an LLM output is non-deterministic, you may want to run this several times, checking for errors, as we did with option 2.
This has been fun, let’s never do it again
After a documentation team has had to rename a product or term once, perhaps twice, they will often ask "could we just make the name parametrizable, so we can switch it out the next time the company renames it?"
Document attributes
One obvious solution, is document attributes. I dislike this solution, for reasons I’ll try to explain, but it’s certainly an option that’s even documented as a good practice:
Most of the time, user-defined attributes are used as a text replacement tool. These attributes allow the author to define named, reusable content. Thus, instead of having to repeat text throughout the document, such as a product name, that text can be defined in an attribute and referenced by its name instead. This technique helps to keep the document DRY, which stands for "Don’t Repeat Yourself".
So we could refer to an attribute defined, for example, in the Playbook.
Create an {acorn-name} runner instance.
asciidoc:
attributes:
acorn-name: Acorn
This looks initially appealing, and will certainly work for simple cases. You should probably consider this simple solution before moving on. But there are some problems:
-
now when you look at your built site, and see the term "Let us create an Acorn runner instance", you can’t easily find this in the source, because that string doesn’t exist.
-
you have to think of names for these names… Perhaps you could use
{acorn}instead, which would look nicer. But what about product names with spaces? -
If the term you are translating is not automatically capitalized, then you’d want that to respect context ("Database" vs "database" for example.) Unfortunately Asciidoc attribute names are case-insensitive so
{database}and{Database}refer to the same attribute. -
If the key is not defined in the playbook or the component’s
antora.yml, then:-
it will be rendered literally like
{acorn-name}. In this case, the naming of the attribute may be key to showing something useful. -
an error will be created in the output of
npx antora generatecommand. Whether you spot this may depend on how noisy your logs are (e.g. if you’re starting with a small, clean build, or have inherited a legacy build where fixing errors in many old versions is a significant effort. TODO link to section on summarizing and squashing build errors.)
-
And of course, the most egregious issue, if we update acorn-name to a word that begins with a consonant, we have to update both files anyway.
Create a {acorn-name} runner instance.
asciidoc:
attributes:
acorn-name: Squirrel
In short, Asciidoc attributes are not general tools for localization. Use them judiciously if they work for you, but be aware of the cases where you will need a more expressive abstraction.
A question of style
We touched briefly on stylisation of terms. For example Knuth’s famous TeX is stylised TEX.
For example Knuth's famous https://en.wikipedia.org/wiki/TeX[TeX]
is stylised *T~E~X*.
We want to keep these consistent, but also easy to write. It’s easy to imagine writers mis-stylising this in different places, without strong discipline.
Let’s see how attributes work here:
asciidoc:
attributes:
tex-name: *T~E~X*
Donald Knuth created {tex-name}.
This results in:
Donald Knuth created *T~E~X*.
That doesn’t work due to the how attribute substitution and formatting are ordered. A workaround is:
Donald Knuth created pass:a,q[{tex-name}].
This uses the inline pass macro with custom substitutions for attributes and quotes (where the bold and subscript are defined as "quotes".)
This is a hard sell to a writing team, and unlikely to be adopted with any enthusiasm as a solution. Let’s look at some alternatives.
Towards a solution
Having looked at this problem from a number of angles, we can summarize some important requirements.
-
It must be easy for the writers to maintain.
-
It must be easy to find the terms to rename, without finding false-positives.
-
We may want to be able to stylise terms according to complex formatting rules.
-
We might want to do automatic renaming, including changing the surrounding text (like "a/an" in English.)
Let’s look at a possible option that covers items 1-3. Item 4 can be left as an exercise for an LLM, or for an ambitious custom extension.
Index terms
Asciidoc provides an Index Catalog feature. This allows the automatic creation of an index, currently for PDF and DocBook targets, but not HTML.
By default, you can write text like:
In ((Acorn Runner)), we can create (((task)))tasks.
This creates an index entry for ((Acorn Runner)), but also outputs the text "Acorn Runner" in the document.
It then creates an index entry for which outputs nothing.
This allows us to write custom text to show to the user, in this case the plural "tasks".
Already, this is arguably more useful than document attributes, in that we’ve not had to invent any names for these, and can just write human readable text!
This builtin feature partly addresses our first two requirements:
-
Writing
((Acorn Runner))is no more difficult than writingAcorn Runner. -
It is easy to search (using your text editor’s Search and Replace feature) for
((Acorn Runner))to find all deliberately tagged instances of this term. Because we’ve specified the double-parentheses, we won’t find any examples that weren’t previously tagged as terms, and which might be the edge cases we’ve already discussed. That’s a good thing: we handle the low-hanging fruit this way, and then do an additional search for non-terms, to edit with greater caution.As a bonus, by default, we’ll also find instances of
(Acorn Runner)with 3 sets of parenthesis (the hidden entries).
Extending index terms
Though we can use the text editor’s Search and Replace, it seems appropriate for a feature that creates an Index to usefully summarize the locations of these entries, across all components and versions.
With relatively little code, we can:
-
generate such an index by hooking into the processing of the underlying
indextermmacro. -
add stylization to the feature.
This will allow us to:
antora:
extensions:
- require: ./lib/terms-extension.js
data:
styles:
TeX: '*T~E~X*'
Acorn Runner: "Acorn Runner"
Donald Knuth created ((TEX)).
In ((Acorn Runner)), we can create (((task)))tasks.
Donald Knuth created TEX.
In Acorn Runner, we can create tasks.
Notice how we’ve even mis-capitalized TeX, but added a fallback.
This kind of detail will make it easier to maintain and keep consistent.
The output, if periodically analysed, will help show terms that are duplicated due to inconsistent spelling, and track them down for correction.
-
Acorn Runner
-
acorn run
-
Acorn Runer
-
…