Written by Mark L. Levinson

Some writers labor to keep their sentences uncluttered but clutter their examples with items that are distracting or even dangerous. If an example calls for a list of usernames, they’ll list their favorite basketball players or favorite fictional characters. But your favorite basketball player sells his name for use on sport socks for millions of dollars. You shouldn’t assume in your manual that his name is free for the taking. And for every reader who smiles in recognition when he sees a character’s name from your favorite movie, another reader thinks that the movie was stupid and assumes that you and your product must be stupid too. Anyway, the names in examples should not compete for attention against the point that the example is making.

Sometimes you don’t have much control over the names that appear in examples. They come from the GUI as screenshots right at the development site and for that reason the names of the writers and developers are all over them. What is a writer supposed to do then, tweak the screenshot bitmap to substitute “John Doe” for “Jacob Dotan”?

Yes, that’s the best thing to do. Even if the names on the screen are simple not odd-looking for the non-Israeli reader, the names of the company staff should be kept out of examples. As e-mails fly, with your clients consulting your salesmen and your salesmen consulting your developers, someone may notice that people’s names in the manual are the same as people’s names in the company. The impression then is that you and your product live in a garage-sized world and have never withstood the reality of field conditions.

Rather than reminding the reader that the examples come out of the lab, you should try to give the impression your product is used extensively in real life, that you are well informed regarding that usage, and that you have many true examples at your disposal that you may be thinly disguising as you write the manual. To maintain that psychological impression, avoid data that is intrusively unlikely, like an address of 123 123rd Street or a sum of $44,444.44.

For addresses, you can make up reasonable-sounding towns that don’t exist — I’m fond of the town of Durville, Massachusetts — and you can use ZIP codes that don’t stand for anyplace. (To find unused ZIP codes in any particular state of the USA, start at http://en.wikipedia.org/wiki/List_of_ZIP_Codes_in_the_United_States .)

For American phone numbers, you can use the 555 exchange, the way the American movies and TV shows do to keep curious people from bothering real phone users. (See http://en.wikipedia.org/wiki/555_telephone_number .) It’s obviously artificial, but if Hollywood can use it without ruining a spy thriller, you can use it without ruining a manual.

Similarly, I think that the time-honored names for arbitrary people are the best — John Doe, Jane Doe, Richard Roe. For more names, see http://en.wikipedia.org/wiki/John_Doe or just use some Smiths and Joneses. Like the 555 exchange, they may be obviously artificial, but they’re so conventional that they’re transparent rather than distracting.

Another school of thought favors original names, but with a politically correct rainbow of ethnicity. The problem there, I’m afraid, is that if you check Google you’ll find someone — and not just someone, but someone with a certain public reputation — matching almost every name you can think of. You can increase your odds of originality by going cross-ethnic — as of this writing, Google knows of no Giuseppe Malone or Lyuba Garabedian — but then once more you risk distracting the reader with intrusively unlikely data.

Like phone numbers, URLs in examples should be fictitious. The domains example.com, example.org, and example.net are reserved for the purpose. For an IP address, you can begin with a number over 255, which is technically impossible in the actual Internet protocol.

In writing examples, be the opposite of a good news reporter: keep the information fictitious, and keep it uninteresting.

Comments and questions are welcome:

All Why of Style Articles