Daniel D. Beck

When is it safe to use “new” in technical documentation?

“New” is one of those words that many tech writers say you should never use. Many style guides discourage the use of “new”, too. Using “new” supposedly presents a bunch of threats:

But some things are, in fact, new and you might need to communicate that fact. How do you resolve this conflict?

Instead of forswearing “new” altogether, you can learn how “new” works (and why it sometimes fails). If you want to know how to use “new” safely, then you need to learn about how some words are marked and unmarked.

Linguistic markedness provides a useful test

In linguistics, “markedness” describes when a word (or other structure of language) has a conventional, regular form and a diverging or “marked” form. For example, English prefixes such as “un”, “dis”, or “a” often do this marking:

Doesn’t have a mark Has a mark
Documented Undocumented
Labeled Unlabeled
Respect Disrespect
Historical Ahistorical

Generally, given a pair of marked and unmarked forms, the unmarked form is more preferred or general, while the marked form is less preferred or specific. In other words, unmarked forms are the default, while marked forms are irregular.

This is how something like “one giant leap for mankind” can be widely understood as a generalization to “one giant leap for humanity” while “one giant leap for womankind” could not be widely understood to have the same meaning. “Man” is unmarked while “woman” is marked; I think you understand what that says about anglophone cultural hierarchy. Looking for marked and unmarked pairs can reveal lots of biases baked right into the language—try it out!

The power of markedness is strong enough that it works even when you’re unfamiliar with the marked/unmarked pair. If I were to offer you a choice between “foo” and “xfoo”, then you would intuit that “xfoo” is probably some divergent form of “foo” without even knowing what “foo” is (if it’s anything at all, which it’s not).

Sometimes this effect works so well, if you encounter a word or phrase that sounds like it is marked, you might nonchalantly infer the existence of an unmarked form, even if it doesn’t really exist. And then you might will it into existence.

This has important ramifications for technical documentation, where readers are going to rely on what they do know—like the signal of marked and unmarked forms—to navigate their unfamiliarity with the content.

“New” is a mark

What does this have to do with the word “new”? “New” is a mark.

For example, suppose you’re documenting a product that has two versions coexisting, one older than the other. There’s a strong tendency to mark one or the other:

Doesn’t have a mark Has a mark
SomeProduct New SomeProduct
Feature Beta Feature
Widget Legacy Widget
N/A Ono-Sendai Cyberspace 7

Version numbering is a kind of mark, too.

When you mark a product or feature name, it implies to readers that the marked version is deviant in some way (with a narrow exception for the case when there’s no unmarked equivalent—if you always affix a version number, then there’s no unmarked form to contrast against).

Usually that deviation has an intentional emphasis. For example, if you have “Widget” and “Legacy Widget”, the “legacy” mark communicates uncertainty about the marked version’s future and shows a preference for the unmarked version. It says, in fewer words, that you should use the unmarked version instead.

Sometimes a mark can have unintended implications. For example, if you mark “SomeProduct” as “New SomeProduct” then you might intend to communicate progress, change, or excitement. But because it’s the marked rather than unmarked form, it also communicates uncertainty. “New SomeProduct” may suggest progress, but it also suggests immaturity.

Marking something is high risk in technical communication because it can suggest things you don’t intend. When you apply a mark, consider that you’re not merely distinguishing between two similar things; you’re making an implicit recommendation to your readers.

Use “new” wisely

“New” is best used in limited situations, when the markedness helps, rather than hinders, your intended meaning. Avoid it in other situations.

It’s good to use “new” when you want to emphasize the difference of the marked form, such as to encourage caution or skepticism.

It’s OK to use “new” in content that’s explicitly fixed to a specific time and place, such as release notes, conference talks, and social media posts, where your audience knows that something “new” in 2015 probably isn’t new today. In these cases, the “new” mark aids the ephemeral character of the content—though they’ll probably go looking for something more contemporaneous.

It’s OK to use “new” grudgingly when it’s part of the thing you’re writing about. If “new” is a formal part of a product name or appears in the user interface, then don’t evade the truth. If you can’t change the source text, treat it like you would other text that must be handled verbatim. “New Mexico” is distinct from “Mexico”; you can’t make that distinction without the “new” mark, so don’t try.

Avoid “new” in content that’s meant to be durable, such as reference documentation. It won’t be “new” for long and your users aren’t going to look for a last-updated date to understand what you meant by “new”. In these cases, the markedness undermines your goals.

“New” isn’t a dirty word, but it’s one that’s trickier to use (or not use) than it looks.