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 john.smith@yourcompany.com” in your document.  However, there’s one problem: John Smith no longer works for the company.  The correct contact is john.public@yourcompany.com.  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. HelpDesk@yourcompany.com) 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.

Advertisements

Is Your DR Plan Complete?

Here’s another article reblog, this time from my friend, Andy Levy. Disaster recovery is a big deal, and you need to make sure that you’re prepared.

Don’t think a disaster can’t happen to you? Well, it happened to me.

The Rest is Just Code

Kevin Hill (b|t) posted a thought-provoking item on his last week about Disaster Recovery Plans. While I am in the 10% who perform DR tests for basic functionality on a regular basis, there’s a lot more to being prepared for disaster than just making sure you can get the databases back online.

You really need to have a full-company business continuity plan (BCP), which your DR plan is an integral portion of. Here come the Boy Scouts chanting “Be Prepared!”

When disaster strikes:

  • How will you communicate it to your customers, including regular status updates?
  • How will you communicate within the company?
  • Do you have your systems prioritized so that you know what order things have to be brought online? Which systems can lag by a day or two while you get the most critical things online?
  • Do you have contingency plans for all of…

View original post 543 more words

Maintain Your Trustworthiness

This is a reblog of an article written by my friend, Steve Jones. I would hope that this is something that goes without saying among data professionals like myself, but I think that it’s important enough that it’s worth repeating (and reblogging).

Voice of the DBA

Many of us that are DBAs and/or sysadmins find ourselves with privileged access to many systems. We can often read the data that’s stored in these systems, whether that’s a relational database, a NoSQL store, or even a mail system. As a result, it is incumbent upon us to be trustworthy and maintain confidentiality with privileged information.

Overall I think most of us do this, but there are always some rogue administrators out there, some of which might take malicious actions. There have been a few people that were arrested or sued for hacking into systems, trashing backups, or causing other issues. Often those are emotional outbursts that disrupt operations, and many people are aware there is an issue. However, what if people weren’t aware they were being hacked in some way?

I ran across this story about some “admin” software being sold on a hacker forum site, which was…

View original post 309 more words