mike's web log

Terms of venery, IT style

Mon, 25 Mar 2013 11:36:47 GMT

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

Contributors: me, David Huntsperger, Peter Delaney, Scott Kralik

Hurray, new & improved technology! What do you tell users?

Wed, 13 Mar 2013 09:02:44 GMT

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?

[more]

Rocket Science for Beginners

Thu, 31 Jan 2013 10:31:33 GMT

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.

[...]

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).

Frankly, I'm not really sure how grateful my wife would be to learn these things.

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.

[more]

The 10-ton truck on the 2-ton bridge

Sat, 01 Dec 2012 11:57:12 GMT

We got a customer comment the other day observing that we had a contradiction in our documentation. In one topic, we note that the maximum size of a particular document type is 128K. In another topic, we note that the maximum is between 2K and 10K (dependent on some technical details).

We investigated. The results were a little surprising: seemingly paradoxically, both topics were technically correct. The 128K limit pertains to a transport limit — it's the largest document that will be accepted for upload. The 2K-10K limit is a business rule that is invoked later when the document is being saved.

It's like a 10-ton truck trundling down a road. Maybe the weight limit on the road is 50 tons. However, if the road crosses a bridge with a weight limit of two tons, that's the effective limit for the whole road.

We contemplated various ways to fix this problem. A complicating factor was that the text about the 128K limit was generated into the documentation automatically. (By a JavaDocs-like process, if you're curious.) The particular conundrum was how to explain, yet dismiss, the 128K limit in a way that made sense to the customer, since for the most part there is no practical circumstance under which the clearly documented 128K limit actually made sense.[1]

[more]

Alpha to Z: User-oriented name order

Tue, 20 Nov 2012 22:47:48 GMT

At work the other day I was working a list of our products and I found I kept hunting around in the list for a specific one. Here's how the list was arranged (I left a few out for brevity):

Amazon CloudFront
Amazon CloudWatch
Amazon DynamoDB
Amazon Elastic Compute Cloud (Amazon EC2)
Amazon Elastic MapReduce
Amazon Glacier
Amazon Relational Database Service (Amazon RDS)
Amazon Route 53
Amazon Simple Email Service (Amazon SES)
Amazon Simple Storage Service (Amazon S3)
Amazon Virtual Private Cloud (Amazon VPC)
Amazon Web Services Account Billing Information
Auto Scaling
AWS CloudFormation
AWS Elastic Beanstalk
AWS Identity and Access Management (IAM)
AWS Storage Gateway
AWS Support
Elastic Load Balancing

It's a bit more obvious here than it was in the document I was updating, but you can see that the products are arranged in strict alphabetic order. (You might wonder, as I did, why sometimes it's "Amazon" this and other times it's "AWS" that, but what you see here are the official product names, and there's no messing with that.)

Still, and in spite of this perfectly logical order, "Elastic Load Balancing" at the end felt like it had been tacked on as an afterthought. Likewise "Auto Scaling" felt out of place, and seeing Amazon CloudWatch separated from AWS CloudFormation was odd.

Putting things in alphabetical order has a number of recognized challenges. You need to decide whether you're going to sort case sensitively; how to accommodate spaces and punctuation; how to handle acronyms and initialisms; and so on. (You can explore some of these under Special Cases [more]

Try and understand this

Fri, 19 Oct 2012 10:42:53 GMT

The legitimacy of try and in the sense of try to has been debated for a long time, but it's an established usage in informal English:

I'm going to try and be there at five o'clock.
Please try and understand my point of view.

(For a good summary, including OED cites, N-gram stats, corpus search results, and a blessing from Fowler, see the blog The Writing Resource.)

Objections to try and sometimes seem a little forced; for example, Grammar Girl posits an argument from logic: "If you use and, you are separating trying and calling. You're describing two things: trying and calling." She goes on to say that try-and versus try-to may be more of a pet peeve with her.

And yet. I ran across an interesting example today of try and where I had to read the sentence a number of times before I got it:

If you try and lose then it isn't your fault. But if you don't try and we lose, then it's all your fault.

This is from Orson Scott Card's book Ender's Game.

The intent, as I eventually deduced, was "If you try and [you] lose ...". For my first several attempts to read the sentence, I kept parsing it as "If you try to lose ...", which didn't completely make sense. But first readings are stubborn. In other words, the intent is per Grammar Girl's logical parsing (two actions), but I was not reading it that way.

I think some punctuation here might have helped — a comma after try. Or an extra you inserted after try and.

Speaking of [more]

Headline fun

Wed, 26 Sep 2012 23:43:18 GMT

Friend Dennis spotted the following headline on the website of one of our local TV stations:

I can't really improve on Dennis's comment: "I guess it's better than shooting him with bullets."

It's a great example of the ambiguity that can arise in the term with, which can function either to mark a relative-type clause or to mean "by means of":
Officers who shot man [who has] dementia
Officers who shot man [by using] dementia (haha)
Back in my editing days (ha), we policed the use of with carefully. This would be an example of why we did that.

PS "SPD" is Seattle Police Department, in case that's not clear.

PPS The headline is cooked right into the article's URL, too.

Key remappings in Word

Tue, 11 Sep 2012 16:55:45 GMT
This is a blog post just to record the key remappings I do in Microsoft Word 2010. (It is probably not of interest to most people.)

I've found that it speeds up revisions tremendously to map keyboard shortcuts to the commands in Word that you use to find, accept, and reject revisions and comments. As a bonus, I don't like that the traditional Find key in Word 2010 is mapped to some sort of Navigation pane (where traditional Find is available under Advanced Find). So I map Ctrl+F as well. As I say, this is primarily for my own reference.

Task Command Key mapping
Display Find/Replace dialog box EditFind Ctrl+F
Find next revision or comment NextChangeOrComment Ctrl+Shift+F
Accept current change AcceptChangesSelected Ctrl+Shift+A
Reject current change RejectChangesSelected Ctrl+Shift+R

Spellcheck typo

Thu, 06 Sep 2012 13:06:54 GMT
Someone at work spotted this great example of a typo that was almost certainly introduced by spell checking (aka a Cupertino):

The original is on the techradar.com site, tho they might fix it eventually. However, for the time being, it's even embedded in the URL:

http://www.techradar.com/news/mobile-computing/tablets/amazon-announces-kindle-paperweight-1095267

Two editorial curiosities

Thu, 23 Aug 2012 11:53:24 GMT
I'm on hiatus at the moment (more on that next week), but I did want to break radio silence briefly to note a couple of editorial things that I've run across recently.

The first is a variation on the common confusion between rein and reign. For example, people often write reign in when they mean rein in.[1] However, I've never personally seen that confusion extend to a context where it's this clear that we mean the straps you use on horses. This is from a Netflix capsule summary:

Maybe I just haven't been paying attention.

And a second one is just a somewhat curious use of the expression "+/-". This is familiar to me to suggest numerical tolerances. So I don't quite get the motivation for using it in this sentence from a running website:
Avoid running during the hottest part of the day. Listen to your body and stop exercising, find a shaded, cool area, and rehydrate (+/- seek medical attention) if you experience lightheadedness.
If I were writing this out, I'd write something like "and if necessary ...", but I've never seen +/- used to mean that. Do they mean and/or? If so, is +/- shorthand for that?

[1] Tho I think that this particular confusion is understandable, since to my mind reign in could be something that constitutions do to chief executives.

Punctuating a, long and wordy, qualifier

Mon, 02 Jul 2012 10:20:14 GMT
I found this in a comment on a blog post:
The, not really qualified for the position of teacher, instructor never bothered to use Notepad++.
I like this, because the author has the right instinct: there's a complex modifier for the word instructor, and he understands that it needs to be typographically indicated to make it parsable. The usual way is to hyphenate the whole dang thing:
The not-really-qualified-for-the-position-of-teacher instructor never bothered to use Notepad++.
Or a more boring way is to recast, e.g.:
The instructor, who was not really qualified for the position, never bothered to use Notepad++.
But that takes a certain oomph out of the sentence. It's possible that "Scott" considered hyphenating but was not comfortable; creating a chunk of hyphenated text like that takes a certain determination, and a faith that the reader will plow through it. Obviously, yer various style guides are not going to be down with using commas as the alternative. Still, like, I say, I do like this. It shows a writing mind at work.

If I signup, they'll sendout their newsletter

Thu, 28 Jun 2012 12:22:30 GMT
From an email. My linguistic sensibilities tell me that this is an irreversible trend. My editorial sensibilities nonetheless chafe a bit:

See also: To set up is not to setup.

Really the surprise here is the source: the venerable, editorially conservative New Yorker.

Be sure to document that

Wed, 20 Jun 2012 16:20:25 GMT
Another instance where documentation is used to fix a design flaw:

More dubious guidance

Mon, 07 May 2012 21:58:46 GMT
Normally I am interested in product instructions that are of dubious utility, let's say. (Previous) Today, tho, I ran across more of a wtf moment. My wife bought a new iron over the weekend. The cover of the instruction manual makes this interesting offer:

In case you can't see it clearly, the manual for a steam iron is suggesting that we visit the manufacturer's site for "delicious recipes." I mean, I've heard of a flat iron steak, but I didn't realize that this is what they meant. Iron chef?

More dubious guidance: 1, 2, 3, 4, 5, 6, 7, 8

"This is pre-release software"

Thu, 03 May 2012 09:13:13 GMT
You do want to remind your early adopters that they're dealing with things that are not completely baked. There are ways to do that, and there are other ways.

Here's us:

Disclaimer

This is a preliminary document and may be changed substantially prior to final commercial release of the software described herein.

Here's them:

Not for the faint of heart
Canary is designed for developers and early adopters, and can sometimes break down completely.

Nightly updates
Canary changes almost every day.

Dumb instructions that are actually pretty smart

Mon, 23 Apr 2012 20:58:19 GMT
Last week I moaned about what I considered some dumb instructions. This week I'll praise some instructions that probably look pretty dumb, but I thought were actually pretty smart.

First, the instructions. The scenario is that you have an ad posted on Craigslist already and you then edit it. When you save your edits, this is what you see:
YOU ARE FINISHED EDITING. THANKS!

READ ALL OF THIS! -- TO SEE YOUR CHANGES:
Go see your ad at http://seattle.craigslist.org/est/msg/nnnnn.html
While viewing that page, hold down the 'Ctrl' key and press the 'F5' key.
The page should now show your ad, with your new changes included.
Your edits have been made. If you still don't see them after the above steps, try restarting your browser and looking again.
One of the complaints I had last week was that some of the steps ("Click Next") were telling the reader to do something blind, without the context of what you were actually accomplishing. But hey, look! These instructions do something that's arguably the same thing:
While viewing that page, hold down the 'Ctrl' key and press the 'F5' key.
What they really mean is "refresh your browser." (Also, they mean "Press Ctrl+F5".)

So why do I like these particular instructions? It has to do with understanding your audience. Last week's instructions ignored the fact that the audience was Microsoft employees — people who have run similar procedures many, many times.

[more]

Dumbest instructions I’ve seen this month

Sun, 15 Apr 2012 23:51:34 GMT
I recently ran across the following set of instructions (the name of the app — MyApp — is changed, but they're otherwise verbatim):

Setup Instructions
1. From the Setup Location, run MyApp.msi.
2. Click Next.
3. Click Next for the default install location, or set the install location.
4. Click Next.
5. After installation is complete, click Close.

This a terrible set of instructions. For starters, an .msi file is an installation program (Microsoft Installer). When you launch an .msi, it starts an installation wizard. A wizard (a.k.a. assistant), which is to say, a process that walks you through each step of the process. Wizards were created precisely for multi-step processes so that users didn't need step-by-step instructions. And it doesn't matter whether you know that an .msi file will launch the wizard — all you need to tell people is to launch the .msi, presto, done. If this just seems too bald for you, well, fine, add "... and follow the on-screen instructions" or some other yeah-yeah-whatever text.

Second, these instructions are not telling you what to do in context. "Click Next." Click Next." These instructions are like telling someone how to do something blindfolded.

Third, when they do provide a pretense of information ("Click Next for the default ..."), they're a) repeating what the wizard is already telling you and b) telling you, essentially, "make a change, or don't." The instruction doesn't provide any useful information about how or why to make a choice, just that you might want to (or not). Which will already be evident from the wizard, see point 1.

[more]

Can spelling be irrelevant even on a resume?

Mon, 09 Apr 2012 17:40:51 GMT
A follow up to last week's post (I am conflicted about typos). In that post, I mused about whether it really was that big a deal for people to confuse words like principal and principle, given how confusing English spelling is and how hard it seems to be for otherwise intelligent people to keep these sorts of things straight.[1]

Reg Braithwaite actually went me one better last week and asks whether typos are important at all. Here's the money shot from the blog entry in which he discusses this, talking about candidates for a programmer job:
The problem with filtering people by spelling mistake is that we're making up a little theory about whether a spelling mistake tells us something important about the candidate's abilities. Which would be fine if we didn't have anything else to go by, but we do have something else to go by, we have their resumé and their code samples and we can call them on the phone and talk to them. So I gnore the little theories and go with what really matters.
The man has a point: if the candidate can code like a demon, exactly how does it matter whether he or she can spell? Even on his/her resume.

I realize that people are ... offended ... by spelling errors, but the question here is when is and when isn't spelling ability an issue? I don't have to make much of a case in favor of having mad spelling skillz, since the default presumption is that everyone should have 'em. Braithwaite alludes to a theory that people develop in the face of spelling errors. One popular theory is that bad spellers are lazy [more]

I am conflicted about typos

Tue, 03 Apr 2012 09:46:24 GMT
Here are some things that I believe about spelling and typos:

Our spelling system in English is sort of absurd. The same spelling can be pronounced different ways (lead: leed, led); the same sound can be spelled different ways (right, rite).

Many people who are extremely intelligent are not very good spellers. I see evidence of this every day at work, where people who are in the stratosphere of accomplishment send emails that include typos that are more than just fat-fingered "teh". Or for that matter, people who know a great deal more than I do about car motors, tax accounting, water heaters, phlebotomy, electrical panels, or diminished 7^th chords might not be sterling spellers.

Some spelling errors are so common that they’re called out in usage guides and there are entire sites devoted to the apparently futile effort to sort out the spellings once and for all.
So we have a confusing, inconsistent orthography that seemingly cannot be mastered by even accomplished people in spite of endless efforts to educate them. Anything wrong with this? Should we consider our current spelling system to be within the bounds of success? It seems sort of like designing a product that a significant percentage of users could not figure out how to use right.

And yet. In spite of knowing this, it’s almost impossible to set aside the instinctive negative reaction to typos. This has come up a couple of times recently in online articles:

Microsoft: Metro’s Not Just an Interface, It’s a Philosophy
[more]

Chunking and organizing: headings

Mon, 19 Mar 2012 17:32:37 GMT
Microsoft Word has built-in styles for up to 9 levels of headings. It makes me think that someone wanted to be very sure that customers did not call Tech Support complaining about running out of heading levels. But it also horrifies me because, gah, 9 levels of headings?!?

Headings serve two purposes: chunking and organization. To generalize madly, the organizational aspect benefits writers, and the chunking aspect benefits readers. I've seen examples of both that I think are not doing it right.

Chunking: good. It's pretty well established that readers who are looking for information don't prefer long stretches of text. Chunking the text makes it easier to scan and provides some textual relief.

This can be overdone, tho. If you find yourself with headings that have one or two sentences each, maybe you're not really doing the reader much of a favor. Here's an example — look under Event Subscriptions. Does this section really need three subheads?

A more common problem I see is heading levels used to excess. In a long document, it does help (the writer for sure) to establish a hierarchy that reflects the organization of the material. I recently worked on a What's New document that runs about 46 printed pages and that features 3 levels of headings. (The table of contents (TOC) at the top shows a bird's-eye view of the structure.)

[more]

"All you need is a good text editor"

Sun, 11 Mar 2012 23:58:03 GMT
Now and then I'll run across people who not only sort of hate Microsoft Word, but will say that all they need is some-writing-technology. A subset of these people will go so far as to wonder why anyone would need anything other than some-writing-technology. (For example, I have in the past heard someone say that all he needed was WordPad, and why did anyone need anything else?)

My fondness for Microsoft Word is no secret (I'm composing on it as I write this), so I always feel slightly rankled when I encounter this attitude. This is ~~particular~~ particularly true for the "why would anyone need Word" contingent.

Recently Hilton Lipschitz wrote a blog entry in which he talked about the virtues of Markdown. Markdown is (to quote John Gruber, its creator):
... two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML.
Markdown supports the type of formatting that most people need most of the time: character formatting (bold, italics); paragraph formatting (headings, block quotes, lists); links; images; code formatting; etc. It has a pretty close mapping to HTML elements, but HTML is only one of the formats into which Markdown can be converted. Markdown is popular with wiki software, because it lets writers perform the types of writing and formatting they need without a) requiring knowledge of HTML and not incidentally b) without opening up the huge security holes that you get when you allow people to use arbitrary HTML.

[more]

Golden Rules of Technical Writing

Sun, 04 Mar 2012 22:32:02 GMT
I've been working on some thots about what we do and how and why. I'm trying to come up with some Golden Rules for technical writing. Here are 12 to get started.

Planning
Produce the information that your customers need. Forget everything else.

To learn what customers need, talk to them.

Take advantage of what's already available in your community, and work only on something where you add value.

Know your audience. Understand what they know (and don't) and how they work.

Know your product. Understand what it's for and explain to users how it solves their problem(s).

Consider that the best "documentation" might not be documentation. It might be good product design instead.

Don't assume producing documentation means writing. It might mean producing video, audio, or some interactive something-or-other.

Prioritize. You can't produce everything, so produce the content that has the highest impact.

Writing

Remember that people turn to documentation only as their last choice, and write accordingly.

Focus on 3 C's (in order): correct, clear, concise.

Know what you need to say, and say only that.

Get yourself reviewed/edited.
Agree? Disagree? Items to add? Remove?

If you use "should," it should work

Sun, 26 Feb 2012 20:54:21 GMT
In technical writing, you might see the word should used in a couple of senses.

Sense 1
Example:

After making these changes, you should save the file.

This sense conveys (to quote our style guide) "an action that is recommended, but optional." It's fine, with the qualification that in this sense, should is strictly a recommendation, not a requirement. (If the action is required, use must: To finish the operation, you must save the contents to a file.)

There are variants on this. For examples, error messages are often written this way, as shown here in a couple of examples from our documentation:

Assemblies should declare minimum security.
Enums should have zero value.

Sense 2
Example:

Click New. The New File dialog box should be displayed.

This sense conveys the, um, desired outcome of an action. This usage is relatively common, I've found. But in general, I edit away should when it's used in this sense. When you're writing procedures, you don't want to sound like you're hesitant about what's supposed to be happening. Or to put it a different way, you're conveying a slight sense of doubt about whether the instruction you just gave actually works. Probably it will work. We hope this works. It ought to work.

Contrast these:

Click New. The New File dialog box should be displayed.
Click New. The [more]

The heartbreak of RCS

Sun, 19 Feb 2012 21:52:05 GMT
Millions of Americans have it without even suspecting. But what they don't know definitely can hurt them. Are you a secret sufferer?
Take this simple test

Study these texts:
Turn Left at 148th Ave SE
Go 1/2 mile and turn Left at SE 117th St
Turn Right at 150th Ave SE
Head straight into our Parking Lot [#]
First we’ll create some Model classes to represent Genres and Albums within our store. [#]

[#]

These should look wrong to you. If they don't, then you, too, probably suffer from Random Capitalization Syndrome, or RCS.

What is it?

RCS causes writers to capitalize Words that they think are Important. It is related to, but not the same as, CEWIASS (Capitalize Every Word in a Sentence Syndrome), which often affects children, and it's not to be confused with CELS (Capitalize Every Letter Syndrome), which is sometimes known by the colloquial name SHOUTING.
Where does RCS come from?

Science is still working on the question of where RCS comes from. Theories that have been proposed include the following.

[more]

Editing by analogy

Sun, 12 Feb 2012 23:35:03 GMT
One way in which you can make editorial choices is to rule by analogy. For example, given how often we see the term username in casual writing (emails, specs, stuff written by non-writers), documentation writers will sometimes ask "So, is it username or user name?" There are various ways to research this question: consult a dictionary; consult a style guide; see what the precedent is in existing materials for your audience. If none of these resolve the question satisfactorily, you can fall back on the analogy method: it's first name and last name, so unless someone can convince me otherwise, I'll rule for user name.

I had a similar question recently about the term runtime. Programmers will often write that something or other occurs at runtime. When I got the question, I consulted the usual sources. If those had failed me[1], I'd reason that analogous phrases are at design time or at compile time. Ergo, at run time.

I emphasize that editorial reasoning by analogy should come only after other oracles have been consulted because there are times when established and accepted usage goes against analogy. For example, analogy alone might tell you that if it's folder name and volume name, it should also be file name. And indeed, that's how file name is entered in the Microsoft style guide, where they trouble to point out that it's two words.

[more]

Task	Command	Key mapping
Display Find/Replace dialog box	`EditFind`	Ctrl+F
Find next revision or comment	`NextChangeOrComment`	Ctrl+Shift+F
Accept current change	`AcceptChangesSelected`	Ctrl+Shift+A
Reject current change	`RejectChangesSelected`	Ctrl+Shift+R