Thursday, 7 May 2015
Now and again I'll get a request from an engineer that says, essentially, "We need to update the documentation, because there's this additional way to do the task." For example, I got a request not long ago that we were missing documentation for some alternative ways to specify parameters for a command. The command goes like this:
DoSomething.exe --filename <somefilename>
The engineer wanted us to add that you could also do this:
DoSomething.exe -f <somefilename>
In other words, the
-f option was a shortcut/alternative for the
Similarly, I was recently asked to add a note that told users that under some specific circumstances, they could exclude the filename extension (.pdf or .txt or whatever) from a filename parameter. But leaving off the extension was optional.
When faced with a request like this, the writer might want to take a step back and ask whether the update is really that helpful from the user's perspective: does the reader benefit from this additional information, or does it just add noise? Is this essential information, or is just a nice-to-know?
It's not that these alternative approaches are not useful to users. But does every user have to know every option for every command? Is the benefit worth the extra effort to add them to the docs, and the users' extra effort to sort through the options? What if the alternatives are really just artifacts of the previous version of a command—do we still need to document them?
People who document procedures that involve UI might be familiar with a similar issue. When you're telling the user how to do something, does each step of your procedure describe the menu command, and the right-click context menu, and the keyboard shortcut? This can quickly become cumbersome.
Here's an example of a step from the MadCap Flare documentation that provides an exhaustive inventory of every way to accomplish the step:
Should every procedure step get this treatment? I argue not only that it isn't helpful, but it actually noises up the procedure substantially.
The goal of documentation—particularly reference docs and procedures—is to get the user to the solution as efficiently as possible. If you do get requests to include options for commands or gestures, consider pushing back and asking just how necessary these additional options really are.
Wednesday, 11 February 2015
I am all for writing that conveys factual information and that’s written in an informal style. But some rigor is still required, even then, to keep thoughts and facts on track.
Here’s an example, one complete paragraph, from the book Countdown by Alan Weisman, which (as here) sometimes reads like a novel.
It exasperates him to think of agriculture’s driving incentive being not to feed, but to profit. Reynolds rises and stalks to the window. Both these men have made their careers here, working alongside Dr. Borlaug, authoring papers with him. A Nobel Peace laureate, and yet money to continue his work on the veritable staff of life that launched human civilization, and on which it still depends, is so damned scarce.So, two moments of potential confusion. First, who does “A Nobel Peace laureate” refer to here? Choices seem to include:
Second, what exactly is the relationship between the Nobel Prize and, well, anything in the rest of the sentence that the term appears in?
- Dr. Borlaug
- Someone who does not otherwise appear in this paragraph.
As I say, informal style is ok with me for a book like this. But if a sentence gets to the point where the reader has to stop and think, even informal writing needs some tightening up.
Thursday, 20 November 2014
I’ve had two occasions recently of seeing myself represented in, like, actual books. This is a little startling, in a pleasing kind of way.
The first reference is explicit. In his book Engineering Security (or at least in the April 2013 draft of it—download it here), Peter Gutmann is discussing the problem of putting security decisions in front of users. Here’s a paragraph out of that chapter:
The abstract problem that the no-useless-buttons policy addresses has been termed “feature-centric development”. This overloads the user with decisions to a point where they adopt the defensive posture of forgoing making them. As Microsoft technical editor Mike Pope points out, “security questions cannot be asked on a ‘retail’ basis. The way users make security decisions is to set their policies appropriately and then let the security system enforce their wishes ‘wholesale’”Boy, was I tickled when I ran across that. But I didn’t remember being that smart, so I went to the blog to figure out where I had said such an interesting thing. Alas, although it is true that this information appears on my blog, it’s actually a citation from the eminently quotable Eric Lippert, who knows a great deal more about security than I ever will.
And then today I was reading Steven Pinker’s new book A Sense of Style. This is Pinker’s shot at a guide to writing (i.e., a usage guide), with the twist that Pinker is a cognitive psychologist, so he proposes guidance for clarity and comprehensibility in terms of how the brain processes the written word. (It’s more interesting than I’ve just made it sound.)
At one point, Pinker is talking about how the “geometry” of sentences determines how well readers can comprehend them. For example, it can be problematic for readers to parse long “left-branching” constructions, where qualifiers come at the beginning of the sentence: “if [the modifier] starts to get longer it can force the reader to entertain a complicated qualification before she has any idea what it is qualifying.”
He has a number of examples, including the following:
And here’s another of this examples:
- The US Department of the Treasury Office of Foreign Assets Control
- T-fal Ultimate Hard Anodized Nonstick Expert Interior Thermo-Spot Heat Indicator Anti-Warp Base Dishwasher Safe 12-Piece Cookware Set.
Ha! I thought. I know exactly where he got that last example: from me. Well, sort of. Once upon a time I wrote a blog entry about “noun stacks”—big ol’ piles of words like these examples. In the entry I included a number of examples that I had run across at Microsoft. The blog entry was picked up by the Language Log, which is undoubtedly where Pinker actually found the example. But I know where that example really came from.
- Failed password security question answer attempts limit
Naturally, many people find themselves cited constantly, both formally (like, academics) and in popular writing. I suppose a person can get used to reading along and seeing something they’ve written cited in an article or book or whatever. For me, though, even just these tenuous associations with real books is quite exciting. :-)
Monday, 2 June 2014
Andrey Karpov, who analyzes software for defects, has identified what he calls the "last line effect." This happens when people use copy and paste to quickly create a bunch of similar lines of code. He's figured out that mistakes are most often made in the last pasted block of code. He backs up his thesis with hard numbers and with examples taken from real code. He muses:
I heard somewhere that mountain-climbers often fall off at the last few dozens of meters of ascent. Not because they are tired; they are simply too joyful about almost reaching the top—they anticipate the sweet taste of victory, get less attentive, and make some fatal mistake. I guess something similar happens to programmers.I've certainly made this mistake while writing code. This also made me wonder how often this syndrome is evident in writing or editing. What would this look like? Obviously, there are many pitfalls associated with copying and pasting, but is there an analogue in writing and editing to the last line effect?
Monday, 28 April 2014
As a technical writer, you will frequently find it useful to be on the consuming end of information and to take some lessons away from that experience. I had such an experience today.
I was working with some internal tools and couldn't get things working. I pinged the experts, and one of them sent me back instructions that ran something like this (altered to be suitable for public consumption):
1. Save the attached configuration file.
2. Overwrite the current config file in the X folder.
3. Try the process again.
I saved the file and overwrote the config file. No luck, so I contacted the expert again. I got this response:
Please follow the instructions exactly.
So, I tried again. Still no luck, so I sent a dense response detailing what I'd tried and where it had failed. The expert, I must say, became a little impatient.
Long story short, the process I was trying has two configuration files in two places. I had overwritten the wrong one. The part of step 2 that said "in the X folder" had somehow not penetrated to me, probably because I was looking right at an actual configuration file and I had no reason to imagine that there were two of them. So the "in this folder" qualification hadn't really registered.
It's arguable of course that it's my own damned fault for not reading the instructions carefully enough. But I've done (and indeed, still do) technical support, and I generally don't blame customers for not being careful enough in reading the docs. If instructions aren't working for people, I try to take away a message that the instructions aren't clear enough. I certainly don't respond to confused customers with the message that they're just not reading instructions carefully enough—especially the instructions that obviously don't seem to be working.
But those are after-the-fact issues. What would have prevented the confusion in the first place is for the expert/writer to have anticipated a possible problem, along these lines:
2. Overwrite the current config file in the X folder. (Note that there are two config files—make sure you overwrite the one in folder X.)
That is, it helps tremendously if the writer can anticipate trouble spots and steer the reader around them. Of course, it would be best if processes didn't have such trouble spots—why are there two files with the same name in different folders?—but there are many cases where things are just going to be a bit confusing, oh well.
It would have saved an hour or more of time, not to mention aggravation on both sides, if this small issue would have been anticipated.
So look out for where users might be confused when reading docs. And if readers tell you that they're confused with your existing docs, take that as your problem, not theirs.
Thursday, 9 January 2014
I just installed Word 2013 and was disappointed to note that some of the long-standing keyboard shortcuts no longer work. For example, I've been using
Alt+V,A for years (decades?) to invoke an ancient menu command to toggle between hiding and showing revision marks. Even when they introduced the ribbon and the menus went away, a lot of those old menu-command shortcuts still worked. And some still do; but this particular one no longer does, darn it.
I spent a little while trying to map keystrokes to the show-revision and hide-revision commands in the Review tab. Either I'm not finding them or (as I believe) there's no longer a single command to toggle show/hide of rev marks in the way I've come to rely on.
So, macro time. Using the macro recorder and some editing, I created the following macro and then mapped
Alt+V,A to it. Macros are stored in
Normal.dotm, so as long as that remains available I should be good. (Right?) However, I'll have to update
Normal.dotm on each machine on which I install Word 2013.
Perhaps there's an easier mapping for this functionality. If this macro thing doesn't work out, I'll investigate further.
If ActiveWindow.View.RevisionsFilter.Markup = wdRevisionsMarkupNone Then
' Hide revisions
.Markup = wdRevisionsMarkupAll
.View = wdRevisionsViewFinal
' Show revisions
.Markup = wdRevisionsMarkupNone
.View = wdRevisionsViewOriginal
Tuesday, 4 June 2013
A challenge: you have a conference room and 60 minutes to teach a group of engineers to become better tech writers. What do you tell them?
Monday, 25 March 2013
Everyone knows about a herd of cows and a clutter of cats and a murder of crows, right? These are called collective nouns or terms of venery. (The latter, more interesting, term refers to hunting, should you be wondering.) Many such terms are listed here, here, and on Melanie Spiller's site.
For fun the other day, we came up with terms of venery for the many species that can be found in the world of IT. Herewith our list. Can you come up with more?
A compilation of programmers
A unit of testers
A click of QA engineers
A spec of program managers
A package of builders
A deployment of SysOps -or- A distribution of SysOps
A bundle of network engineers
A row of DBAs
An interface of UX designers
A lab of usability testers
A snarl of IT admins
A triage of Helpdesk engineers
A pixel of graphic artists -or- A sketch of graphic artists
A meeting of managers
A retreat of general managers
A scribble of writers -or- A sheaf of writers
A revue of editors (haha) -or- A scrabble of editors
A project of interns
An oversight of auditors
A tweet of tech evangelists
A quarrel of patent lawyers
Wednesday, 13 March 2013
Imagine that you're a music company in about 1984. For many decades you've been selling vinyl records, and then along comes this newfangled "compact disc" business. It's obvious to your company that this is the future, and your audiophile customers are all excited. But your everyday customers are confused: are you going to stop making records? Are they supposed to replace their enormous record collections with CDs? And what about the whole ecosystem that's grown up around records: record stores, stereo manufacturers, even furniture makers ... what do you tell them?
I've lived through similar scenarios in the software industry multiple times: the company devises a new technology—not just an update to your already successful releases, but a new approach. As with the record company, tho, it's rarely easy to simply pull the plug on your old stuff, since many of your customers are heavily invested in your old technology.
If you're the documentation person under these circumstances, you have a tricky job. If the new technology is sufficiently different, you can create a brand-new documentation set from scratch for the new technology. (The documentation sets for record players and CD players have very little shared information.)
But it's not always that clean a break. Consider a database product where the new technology is an innovative search syntax. Everything else about the database (storage, backup, etc.) is the same; you just have a new way for users to craft their queries. Moreover, the old query syntax still works.
Too often, what ends up happening is that writers add a section to the existing documentation that describes the new technology. This "solves" the problem. Hey, now we have two technologies! We've documented both of them!
But what do your users actually need?
You can accomplish this easily—well, "easily"—in some sort of introduction or overview. But you also have to think about how to help users who drop into your documentation from unexpected places—say, from a web search. Your existing documentation is of course all about the old technology. The descriptions are about the old stuff; if there are examples or illustrations, they're probably about the old stuff. Existing customers will probably continue to use the old technology and will still need documentation for it, so you can't just rip out the old stuff and replace it with new docs.
- All users need to understand that there are two technologies, and why, and how users should choose between them. In your compare-n-contrast, you have to be careful not to trash-talk your old technology (in spite of what your engineers and early adopters probably think); a few years ago, you spent a lot of effort to convince your users how great that technology was.
- Existing users need to understand what the new technology means for them. Do they have to upgrade? What does it mean for their existing investment? How long can they continue to use the old technology?
- New users (probably) need to be directed to the new technology. They also need to understand that there's an existing body of knowledge about the old technology (for example, documentation and articles and books and forums) that could mislead them if they're not aware of the different versions.
You might consider reviewing every page of your existing documentation where the old technology is featured (for example, every page that shows query syntax). Then you have to ask whether you replace the existing examples with new ones, or whether you add corresponding examples of the new syntax. In the latter case, how much explanation do you need in order to make sure readers understand that there are two syntaxes?
As I say, I've lived through this. As of last year, the technology I worked with (ASP.NET) had three distinct approaches to creating websites. We had a heck of a time even crafting the message of how to select between them.
And the idea of visiting each page (page design, database access, deployment, etc.) and updating it for all three technologies—or creating technology-specific versions of each of these stories—was a challenge indeed. (They've since added
a fourth technology fourth and fifth technologies.)
The evolution of a product is of course exciting for users, who get new and improved technology to work with. But unless a new technology represents a completely clean break with the old, and unless you can create separate, standalone doc sets for each technology, in some ways the documenter's job can actually be harder than it is for the engineers.
Thursday, 31 January 2013
The title of this entry does not, as far as I know, reflect an actual book title. But based on something I saw today, maybe it could. Here's an article I saw today on the ArsTechnica site:
Keep it secret, keep it safe: A beginner's guide to Web safety
I was initially interested, because although I am more-or-less conversant with the basics of safe browsing—using wifi safely at a coffee shop, for example—there are certainly other people in our household who might value some tips "for beginners" about how to use the web safely.
Then I actually read the article. Here are a couple of examples of advice for those beginners:
Clicking the browser's padlock icon while visiting Facebook, for example, gives us the most relevant information about the certificate and its encryption algorithms: the certificate has been signed by VeriSign and the connection uses TLS 1.1 with 128-bit RC4 encryption.Frankly, I'm not really sure how grateful my wife would be to learn these things.
If you want to roll your own [VPN] server, you can use free software like OpenVPN (or, for Mac users, the VPN server included in the $20 OS X Server package).
Obviously, the issue has to do with the term "beginner." It's not actually clear to me who exactly the author had in mind as a beginner, but it's not my wife, or my kids, or a bunch of other people who are perhaps not quite ready to examine the certificate chain for the current session.
Scene 2. The other day I was working on a programming problem and someone handed me a working example in the programming language named Python. I don't, er, speak Python, so I had to set up my computer with the requisite tools. In the process of looking for instructions about this, I ran across an article that included the following gems:
You want to use Python on a Windows 7 machine but you don't know what you're doing. What you do know is that in order to go anywhere and do anything you've got to install packages. Or maybe you don't even know that yet.and
The good news is: it's easy.and
There is no bad news.
See all that stuff flying by? Forget about it.I was more than willing to overlook the perhaps too-flippant tone because the article in effect carried out its promise to document the process for (real) beginners.
So. If I see a title that involves the phrase "for beginners," I have a specific idea of what the reader is expected to know (or not know). Perhaps the author of the ArsTechnica article knows something about the audience for articles in that publication such that when he writes "for beginners," he actually means "really technical, but new to this thing." That's quite legitimate, if sometimes a little misleading. (One of the problems I had in finding information about Python "for beginners" is that the assumed starting point for most of the information I found was someone who already knew programming, operating systems (often Linux), tools and technologies (.tar), etc.)
As with any piece of technical writing, you need to have a clear sense when you start of who you're talking to. For a lot of writing, it's not a bad idea to actually lay this out at the beginning of your piece. And if you're going to use a term like "beginners," it seems like you have more obligation than usual to actually indicate what you mean by that.