A black and white issue? - mike's web log/comments

New comments for this entry are disabled.

September 26, 2011 | A black and white issue? | 4011 hit(s)

Not long ago we were working on some security documentation, where one of the writers had written about a whitelist. This term was created by analogy to blacklist. In the context of security, a blacklist contains a list of terms or entities that you want to disallow (block). A whitelist, in contrast, contains a list of only the terms or entities that you will allow. (Whitelists are considered more secure, because it's almost impossible to define a blacklist that will anticipate — hence block — all the entities that malicious users might try to attack your site with.)

Our style guide (MSTP) is unequivocal about the terms blacklist and whitelist: "Do not use." They insist that we write around the terms, using alternatives like these:

Blocked Senders list (for blacklist)
Safe Recipients list (for whitelist)
blocked or safe programs

The style guide doesn’t explain its recommendation. It's not like the terms are unknown in the industry; whitelist gets more than 8 million hits on Google. In fact, it's arguable that whitelist is a more recognized term than the recommended alternatives:

Us: This program lets you define a safe senders list.
Them: Do you mean a whitelist?
Us: Yes.
Them: Then why didn't you say so?

The ban is instead for geopolitical reasons. The term blacklist has various unsavory connotations anyway, but the real problem is that the terms whitelist and blacklist suggest a dichotomy in which white=safe/accepted/good and black=unsafe/undesirable/bad. One of my writers raised a mild objection to this, arguing that the audience for our security documentation would not infer any sociological undertones from its use.

Maybe. It's always a tough argument to make that other people won't interpret something in some particular way. But anyway, you can see why as a corporation we want to stay well away from anything like this that might raise unsavory issues.

But that puts us in a bit of a dilemma. The fact is that because the term whitelist is well known in the industry, people will search our documentation for it. And if the term never appears, what then?

P.S. The style guide does not appear to have an entry for white-hat hacking (versus black-hat hacking). I guess that doesn't come up enough to warrant its own entry.

Presumably because no color-based dichotomy is implied, it is not adamant about other color-based terms. For example, it does disrecommend the following, but only because they're jargon:

black box ("a unit of hardware or software in which the internal structure is unknown, but its function is documented")
black hole ("a condition of an internetwork where packets are lost without an indication of the error")

And of course there's no issue with white space.

Sylvia French 26 Sep 11 - 11:01 AM

"But that puts us in a bit of a dilemma. The fact is that because the term whitelist is well known in the industry, people will search our documentation for it. And if the term never appears, what then?"

I think that we should error on the side of being Helpful. After all, our mission is to Help our readers. Using our special terms for things that they know as a different term already only serves to confuse them. It makes our docs unnecessarily complex and unapproachable.

I had a skip manager back in the Exchange days that forbade us from referring to the product team War Team meeting as the War Team meeting. Never mind that that was the term that it was called by the rest of the org, including all of the attendees. When we referred to it, it was to be called the triage meeting, or something less offensive which I can't recall. The result? We seemed confused, out of touch, and unable to compromise.

Alan Humphrey 26 Sep 11 - 1:27 PM

I believe you should use the terms that people expect.

A possible workaround would be to parenthetically use the offensive industry term when first using the corporate term. For example, "Define your Blocked Senders list (sometimes known as a "blacklist") by....". That way the term shows up at least once and presumably can be searched for.

Of course that doesn't really address the "if you mean blacklist why don't you say blacklist" objection.

mike 26 Sep 11 - 10:35 PM

@Alan -- I was going to respond with "Hey, that's just what we did!" and provide a link, but when I examined the topic where this all came up, it looks like we chickened out after all. (we == I)

In general, tho, I agree: we should use terms that the reader will know. If we have some reason not to want to use those terms exclusively, we should as a minimum include them in a "(also referred to as xxxx)" aside.

Barbara Inge Karsch 28 Sep 11 - 12:41 PM

I fully agree that you should use what people expect, as Alan put it, and I like the workaround. That way, translators could drop the parenthesis around the synonym (“blacklist”) and simply go with the more descriptive term (“blocked senders list”).

On that note, another argument against using a metaphor is that other languages deal with the meaning expressed by colors or other metaphors differently. Your product is probably translated into at least 15 to 30 languages, maybe even more. Ideally, you have a target terminologist look at your key terminology before the start of the translation process and document the target language equivalents. If you have an entry in the terminology database set up, they have all the information necessary to understand the concept represented by the term “blacklist.” But if you don’t have it defined, it might be tricky to come up with an equivalent that expresses what you want blacklist to express; target terms in some languages might turn out wrong or “not quite right”, but at minimum it costs more time to coin the new terms if the original is based on a metaphor.

Don’t get me wrong, I am not in favor of “dumbing down” the source language or “making up stuff” in order to accommodate the translation process. But we cause less downstream problems, if we use geopolitically correct terms expected by our target audience and define them for the translation process. With as many diverse readers as you can expect for a Microsoft product, it usually well worth the effort.