Agnostic document references

Many of you who are technical writers — or data professionals — understand how important it is to not expose real data.  There is a huge emphasis on data security, as there should be.  But a lot of people never think about smaller pieces of data within a document — something as simple as, say, an email address.  In a lot of documentation I write, I make it a point to make much of it as anonymous and agnostic as possible.  There are a number of reasons for this, as I outline below.

I’ll start with a point of emphasis that I make in documentation time and again: know your audience.  Earlier this year, I was responsible for writing a user guide for an application that was to be used by multiple clients.  When I first started working on the document, the application was only being used by one client.  The application — and the document — contained many references to that one client.  In order to update the application to serve multiple clients, all references to the one client had to be removed, not just in the application itself but also in the documentation.  If a document is to be used by multiple audiences, specific client references should be made generic.

Likewise, I’ve accessed applications that display my name on the screen: “Welcome, Ray Kim,” for example.  If I screen-capture that image, I often alter the image so that my name is removed.  I don’t know about you, but I wouldn’t want to be contacted incessantly about an application that I probably know little about.

Another reason is data security, which becomes a larger issue by the day.  Sensitive corporate data risks being exposed within documentation.  For example, for my screen captures and illustrations, I request a “dummy” account that displays “bogus” corporate data for document illustration purposes.  I’ve gotten into the habit where I request this for every document I write.  Corporate data is sensitive; indeed, there is an increasing awareness of keeping such data private (the European Union’s GDPR and laws such as HIPAA and various other data protection laws come to mind).  Live data should never be used in documentation (unless authorized by the client in question); you can never tell what can be revealed in that data.

Here’s another reason I have for keeping documentation generic.  Let’s say, for example, an instruction for additional help directs you to “contact” in your document.  However, there’s one problem: John Smith no longer works for the company.  The correct contact is  But nobody made you aware of this change, nor is anyone aware that this contact is in the documentation.  And who is to say that John Public won’t leave the company or change roles in the next couple of weeks?  Additionally, listing a specific person runs the risk of that person getting spammed by peope who decide to use the contact for reasons other than the one listed in the document.  These risks come up any time a document references a specific person.  A better approach is to reference something more generic — say, a generic mailbox (e.g. or a departmental site.

Here’s another argument for using generic references: how often does the document need to be updated?  Let’s say, for example, you write a document that references “Acme Corporation.”  Over the course of time, “Acme Corporation” changes — perhaps the company is bought or merged, the name changes, and so on.  How often do you need to go through your document looking for “Acme Corporation” and all its variations (shortened to “Acme,” abbreviated as “AC,” misspellings, etc.)?  And suppose your document is hundreds of pages long, with company references interspersed all throughout the document?  Making those edits does not make for a good working day.

Documentation runs the risk of exposing large amounts of data.  For data security, privacy, or even simple editing reasons (and maybe a bunch of others that I haven’t thought about yet), unless there’s a specific reason for not doing so, illustrations, examples, and references should often be made generic.  It’s a simple but critical step that can make your job better as a technical writer, and save your organization from a number of headaches — possibly ranging from complaints from audience members to a lawsuit.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.