Wednesday, August 1, 2012

When design and docs fail

Two Elections Canada workers were fired this week because they didn't understand the difference between encryption and compression. They were told to secure a USB flash drive that held information about voters. Instead of encrypting the data they compressed it, thinking compression was the security feature. Then the drives were stolen. (link)

I have documented encryption and compression, not for end users but for developers. When I read the article I had an immediate understanding (or at least guess) of why the Elections Canada workers were confused. The failure might have progressed something like this:
  1. The internal process of encrypting and compressing data is similar (even though the end use is very different) so when the API was designed, encryption and compression were combined. For example, an API that I once documented used the encode method to both encrypt and compress data. Developers chose encryption and/or compression by setting parameters in the method.
  2. The tech writer followed the API design and documented encryption and compression together. Yes, that's what I did. Even as I did it I realized it was wrong, and I think that's why it stuck in my head. Worse, I went on and on about all the fancy encryption options but threw in compression as a side note. (There just wasn't that much to say about compression: it was essentially a trivial add-on.).
  3. The app developer followed the API design and the API documentation, and again implemented them in one feature in the UI, calling them Encryption and Compression.
  4. The tech writer for the app followed the design of the UI.
  5. The end user was faced with a USB drive that they knew had a security feature, and the UI had two side by side features, Encrypt and Compress. They guessed and chose the wrong one.
I checked out some secure USB drives, and I can see why users would be confused. The terms might be explained in the end user booklet, but if it's not clear in the UI then they probably didn't see it. Or perhaps they saw it but their eyes glazed over because of the lengthy descriptions of encryption algorithms. It would be much better for the app UI and end user docs to separate the two features and call them "Password protect your data" and "Compress data to free up file space." Important features should be completely clear in the UI, without having to resort to the docs. Way back in the API design, security features should have been separated from compression features. At the least, the developer docs should have handled them separately.

2 comments:

  1. A great illustration of what task-based writing is supposed to be about. Alas, today, many interpret task-based writing as meaning a focus on procedures. As you aptly illustrate, it is really about understanding what end the user is trying to accomplish and supporting them in accomplishing that end.

    ReplyDelete
  2. Right. When writing for developers, I think you have to envision two levels of customer: the developer who uses the APIs to create an app, and the developer's customer who uses the app. It's easy to forget the second, but the app user is the whole point of the API so in a sense is the more important customer.

    ReplyDelete