Tuesday, 12 January 2016
I was reading a thread on a computer forum, and someone asked this question:
Quote:This set off an interesting discussion on the semantics of should in this context. I've written about this before, so I was interested to hear how people interpreted the example.
Your password should contain at least 6 characters
If you're going to require it; don't say "should", say "must".
Here is a sampling of the more serious posts on the thread:
From the requirements document: "The password entered by the user should be rejected if it does not contain at least six characters." If I received that requirement from my boss, I would make darn sure that the password is rejected. I don't think I would randomly reject some and not others.
The software is being polite; it's anticipating users who do not like being told what to do.
If it says "should" then it is not optional, like in "could". You should be "this tall" to ride this ride.
A number of people pulled out dictionary definitions (Wikitionary, heh). And one person cited RFC 2119 ("Key words for use in RFCs to Indicate Requirement Levels"), which states:
MUST This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.
SHOULD This word, or the adjective "RECOMMENDED", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.
All of which goes to the original poster's point—the message was ambiguous and should (ha) have been written with must. For those of us who don't keep a mental catalog of RFC recommendations, the more accessible Microsoft style guide says:
Use should only to describe a user action that is recommended, but optional. Use must only to describe a user action that is required.
In documentation, in error messages, in any context where the message needs to be clear and you aren't there to help the reader understand, avoid should when you mean must.
editing, language, technology, writing
Monday, 3 August 2015
From my daughter, another example of poor design patched by documentation.
Who imagined that a) having an unlabeled numeric scale was a good idea, and b) you move the knob to the right for "colder"?
Let's at least fix the first problem, shall we? Like this:
We can't use documentation to fix the problem of having to dial "more cold." But at least we don't to print a frickin' manual right on the freezer.
Update 4 Aug 2015 In response to Hal's comment, here's an improved design that even has redundancy for those who aren't sensitive to color differences.
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