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

Who owns the email?

A while back, one of my work colleagues asked a very interesting question.

“When we send out an email, who owns the copyright?  Is it the owners of the data (i.e. individual clients), or is it the owners of the email (i.e. our employer)?”

He continued to lay out the scenario: “Send it to Client 1. Employee at Client 1 leaks the contents of the email; (our company) has to then cede coypright (sic) to the report so that they can distribute it internall?” (sic)

His final comment: “Imagine if (other companies) did that: ‘You wrote this with Office 365, Microsoft Owns (sic) the copyright'”

That’s a good question.  It’s one to which I don’t have an answer.  To be honest, I don’t have the knowledge or background to be able to answer it.  (Maybe someone who understands legal procedure or copyright law can answer it better than I can; if so, please feel free to comment.)  But I do think it’s an important one, nevertheless.

Email is probably one of the least secure forms of electronic communication.  It is often said that email should be treated like postcards, where anyone and everyone who touches it can read it.  It’s something I always keep in mind whenever I send email.  I refuse to send critical data (passwords, PHI, financial data, etc.) over email.  If I do have a need to send critical data, I’ll look for a way to do it securely, whether it’s data encryption, secure channels, direct messaging (which may not entirely be secure), or even face-to-face communication.  Data security is a big deal (too big to cover in just a single article), and each news item about data breaches becomes a bigger focus (as of this article, the Facebook data scandal is one of the biggest and most recent; sadly, I do not believe that this will be the biggest, nor the last, such breach).

If someone told me that I had to answer this question (and mind you, this is my opinion; do NOT quote me or state this as fact), the original author (or any data content copyright holder) owns any copyrights.  If I sent a song lyric over email, whomever it was that wrote the lyric would own that copyright, but I would own anything that I wrote (that is, something that came from my head — intellectual property — and not from someone else).  The purpose of a copyright, after all, is to protect intellectual property.  However, given email’s open and unsecure nature, original thoughts posted to an email should probably be considered to be public domain.  (That said, if an email sender cites some data source, has he or she committed a copyright violation?  I won’t take the time to discuss that now, but that might be another topic for another time.)

Despite email’s security concerns, it is still a useful tool, and is pretty much ubiquitous throughout our daily lives.  So long as we keep in mind that it isn’t secure, and we can keep our communication habits in context, it is a technology that will likely not disappear anytime soon.