mike's web log

Editing Worksheet -- Part 1: Answers

Tue, 09 Apr 2013 22:10:13 GMT

Last week I posted the first half of a worksheet that we worked on during the recent copyediting class. Here are my notes for the issues in the sentences.

There's plenty of room for debate here. Because the Chicago Manual of Style was one of the class texts, many of the edits are based on that book. Other style guides have different theories about how to manage some of these issues.

Of course, some edits aren't controversial; you do have to spell words and names correctly, for example. Anyway, see what you think. If you have questions about any of the sentences, feel free to leave a comment.

This is the key for the abbreviations used to flag errors:

n.n = as discussed in CMoS reference (might not have definitive answer)
au = consult author to clarify meaning or agree on style
dict = consult dictionary; in general, use first variant.
edb = consult The Eggcorn Database
ssg = consult specialized style guide (e.g. Microsoft Manual of Style)
TCH = as discussed in The Copyeditor’s Handbook
um = consult usage manual (e.g. Garner, M-W Dictionary of English Usage)
web = find authoritative information on the web (e.g. company website)

And here are the sentences.

Gray[dict; American spelling] whales have found a safe place to breed on Mexico's coast, where programs have been implemented to try to bring the marine mammals back from the brink of extinction.

Commercial radio seemed dead, but college radio gave it a new lease[dict, web, edb] on life.

Madeleine Albright[8.3, web] (born May 15, 1937[9.32]) was the first woman to become the United States secretary of state[8.21].

The list contained an extensive list of dos and don’ts[7.13/dict] for practicing good browsing hygiene.

Reviews have found that the data is[um, ssg] flawed in a surprising number of research projects.

Three hundred and twelve[9.5] people showed up in response to an ad for two[9.2] open positions.

You can buy both PDF[10.52] and hard-copy[ssg, dict] versions of the book.

The division generated $600,000[9.24] USD[9.22] in profit on sales of $2.6 million USD[9.4, 9.8, 9.22].

We ask that you please[7.47] tidy up after yourself.

The Tobacco Master Settlement Agreement (MSA)[10.3, 10.4] was entered in November 1998[6.45], originally between the four[9.3] largest United States tobacco companies and the attorneys general[7.7] of 46[9.3; cf 9.7] states.

The reunification of the two Germanys[7.8] was a political triumph, but culturally, the differences took a generation to resolve.

The company maintained a page with an FAQ[10.9] (frequently asked questions)[TCH 228] list.

The People’s History of the United States[8.166] is a highly regarded[7.82] “alternative”[7.55] text that examines the United States’[7.19] development from the viewpoint of the so-called common people[7.56].

The volume of “spam”[7.55] email[7.85/380, ssg] forced the website[7.76,ssg, dict] to temporarily suspend operations.

Each user has a unique name within the account, and a set of security credentials[au, 7.54] not shared with other users.

When signing the Civil Rights Act of 1964[8.79], LBJ[10.12] reportedly said that the Democratic Party[8.65] had lost the South[8.64] for a generation.

One vendor[dict] suggested that the certifying body simply needed to issue more thorough exams.[au for meaning; 7.85/377]

Editing Worksheet -- Part 1

Sat, 06 Apr 2013 10:47:32 GMT

When I was teaching copyediting recently, I came up with a worksheet that contained 34 (!) sentences that might or might not have had editorial issues. We looked at the worksheet at the beginning of class, then reviewed a bunch of editing guidelines in the Chicago Manual of Style (16th ed.), then reviewed the sentences again at the end of class. Other editorial references we talked about in the class (tho these were not readily available) included dictionaries, the Microsoft Manual of Style, The Copyeditor's Handbook, and Garner's Modern American Usage.

Here is the first half of that set of sentences. See what you can make of them. I'll post my notes (not necessarily answers) for this half in a few days.

Grey whales have found a safe place to breed on Mexico's coast, where programs have been implemented to try to bring the marine mamals back from the brink of extinction.
Commercial radio seemed dead, but college radio gave it a new leash on life.
Madeline Allbright (born May 15, 1937) was the first woman to become the United States Secretry of State.
The list contained an extensive list of do’s and don’t’s for practicing good browsing hygiene.
Reviews have found that the data is flawed in a surprising number of research projects.
312 people showed up in response to an ad for 2 open positions.
You can buy both .pdf and hardcopy versions of the book.
The division generated $6 hundred thousand in profit on sales of $2.6M.
We ask that you “please” tidy up after yourself.
The Tobacco Master Settlement Agreement (M. S. A.) was entered in November 1998, originally between the four largest United States tobacco companies and the attorney generals of 46 states.
The reunification of the two Germanies was a political triumph, but culturaly, the differences took a generation to resolve.
The company maintained a page with an FAQ (frequently asked questions) list.
“The Peoples History of the United States” is a highly-regarded “alternative” text that examines the United States’ development from the viewpoint of the so-called “common people.”
The volume of “spam” email forced the website to temporarily suspend operations.
Each user has a unique name within the account, and a set of security credentials not shared with other users.
When signing the Civil Rights act of 1964, L.B.J. reportedly said that the Democratic party had lost the south for a generation.
One vender suggested that the certifying body simply needed to issue more thorough exams.

9 April 2013: Notes/answers for this set of sentences are now posted: Editing Worksheet -- Part 1: Answers.

Copyediting Principles

Tue, 02 Apr 2013 00:13:28 GMT

Over the course of five Saturdays in March, I taught a class in copyediting at Bellevue College. The class is a requirement for students in the Technical Writing certificate program, and an elective for people in other cert programs.

We try to cram a lot into the 15 hours of class, though not at great depth, obviously. Things like what the different levels of editing are—developmental editing, substantive editing, and copyediting. (This class focuses only on the last.) What copyeditors do. What sorts of resources editors draw on. How to interact with authors. How to use revision marks and comments in Microsoft Word. How to create a project style sheet.

The texts are The Copyeditor's Handbook by Amy Einsohn and the Chicago Manual of Style. We spend a lot of time riffling through Chicago in search of guidance for specific situations: Where do commas go? How do you format a book title? Do you use a hyphen with anti- ? Still, the point is not actually to learn a lengthy list of rules for all occasions. Instead, we’re trying to illustrate for the students how and when and why to use a guidebook like Chicago. We had ample opportunity to discuss the limitations of One Rule to Rule Them All, and how the real task is much more pragmatic—help the reader, help the author, help yourself by keeping a style sheet.

For the last class, I put together a list to try to summarize the aspects of the class that weren’t just about finding the right chapter and verse in Chicago or APA or MLA or MMS. I can’t take much credit; I lifted pretty much all of it from people who really know what they’re talking about when it comes to editing.

Here’s my list; annotations follow.

Do no harm
Know the audience
Prioritize the work
Look things up
Have a reason for every change
Ask the author, nicely
Record your decisions
Do things consistently
Review at least twice
Advocate for the reader
Remember it’s not your name at the top
Relax

Do no harm. A mandate from the uber-sensible Carol Fisher Saller. Surely nothing harms the editor’s credibility more than introducing errors.

Know the audience. This is fundamental to writing, of course, but it’s essential that the editor likewise understand what the reader does (and doesn’t) need to know. Scott Berkun has a great blog post that pertains to UI design but that covers some of the same ground. Along with Scott, I wish that I, too, had a t-shirt that said “It Depends.”

Prioritize the work. In TCH (pg 19–21), Amy Einsohn has a brief but critical section on “Editorial Triage” in which she describes how to use your editorial time wisely. “The copyeditor’s first task is to ask the editorial coordinator to help set priorities: Which editorial tasks are most important for this particular project, and which niceties must fall by the wayside?”

Look things up. It might not be inaccurate to observe that the less experienced the editor, the more they trust their own judgment. One way that I can gauge my own level of experience is to think about how often my editorial mentors have answered a question by looking the answer up, and to what extent I’ve learned to do that myself.

Have a reason for every change. John McIntyre: “The whole integrity of editing rests on the editor's ability, when challenged, to give a reasonable and persuasive explanation for every change in the text — and that disagreements over judgments can be worked out collegially, in discussion.”

Ask the author, nicely. Before assuming that the writer is mistaken, why not ask? And don’t be cranky: Katharine O’Moore-Klopf’s advice is simple: “Respect the writer. ” Gary Kamiya: “An editor needs to remember that writing is much harder work than editing. Sending something you’ve written off into the world exposes you, leaves you vulnerable. It is a creative process, while editing is merely a reactive one.” See also McIntyre’s adverb in the preceding point: “collegially.”

Record your decisions. Whatever decision you’ve come to, write it down; that’s what style sheets are for. Melanie Spiller: “If you put your decision in a style sheet, you won’t find editors changing it to suit themselves.”

Do things consistently. It doesn’t really matter that much whether you follow one rule or another rule or you ignore them both and make up your own. Just do it the same way. Readers actually do notice—and wonder about—inconsistency. Carolyn Rude: “Consistency gives useful information to readers. […] Consistency enhances usability.”

Review at least twice. Another voice-of-experience recommendation. On page 243 of TCH, Amy Einsohn lays out her strategy for reviewing tables in three passes, looking for different things with each pass. The wise editor will do the same for headings, figures, and every other element that can benefit from oranges-to-oranges comparisons. That aside, the editor (you) should always review the edits and comments to the author before handing a document back—not only will this catch inconsistent edits and ones you’ve changed your mind about, it will help you tweak the tone of your comments.

Advocate for the reader. The point of all the work is to make the text comprehensible for the reader. The rules exist only for that purpose. Michael Swaine (on writing): “You don’t have to worry about rules of punctuation, spelling, grammar, or usage. It’s not that they aren’t useful, and you ignore them at the risk of impairing your communication. I’m just saying keep them in their place: so far as you as a writer are concerned, those things are just possibly helpful heuristics to help you say what you mean to say, and not say what you don’t mean to say. Writing is communication. Don’t lose sight of that fact and you’ll be all right.”

Remember it’s not your name at the top. It’s the author who ultimately gets the credit (or blame). You help, but they own.

Relax. It’s just editing. Get it done, and then let it go. Carol Fisher Saller again: “The manuscript does not have to be perfect because perfect isn’t possible. […] It simply has to be the best you can make it in the time you’re given, free of true errors, rendered consistent in every way that the reader needs in order to understand and appreciate, and as close to your chosen style as is practical.”

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

Together in a small, crowded, moving box

Wed, 20 Mar 2013 23:52:18 GMT

These days I work in a tall office building, which means that I spend a lot of time in elevators going up and down between office and lobby, not to mention up and down for meetings. Sometimes I run to co-workers in the elevator, but often it’s a bunch of strangers.

I don’t know how international it is, but the protocol for Americans—or let’s say Seattleites, anyway—is essentially to ignore strangers, and to stand facing the doors. Phones help ease the awkwardness of this situation (strangers are so near, yet so ... non-existent), because people can look down and fiddle busily with their phones instead of desperately trying not to make eye contact with other passengers.

But our elevators (and, I assume, those in many other buildings) have a feature that changes the dynamic in interesting ways. Above the bank of floor buttons is a 12-inch screen that displays a rotating selection of news bites, weather, traffic, reviews, deals, and so on. (According to the provider, this “reaches smart, busy, upscale professionals on the move and struggling to ‘do it all.’” Sure, whatever.)

People now have something to look at in the elevator besides the closed doors, or their phones, or the back of the person in front of them. This subtly changes the feel of the constantly changing group going up and down together. They’re watching TV together!

The headlines that are displayed will occasionally move someone to make a remark, or at least to grunt in acknowledgment. This can be an ice-breaker for others … it’s a conversation starter!

Sherry ~~Turkel~~Turkle, who teaches "the Social Studies of Science and Technology" at M.I.T., has recently started to worry that we’re using devices to mediate human relationships for us in ways that actually increase our isolation. Maybe that’s true. But I like to think that our elevators, thanks to technology, might actually now be breaking down the barriers between people in our building.

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?

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

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.

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.

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.
There is no bad news.

and

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.

The case of the bouncing emails

Sun, 27 Jan 2013 12:19:57 GMT

Here's a way not to make friends and not to influence people: hand out your personal email address everywhere and then discover that the address is merrily bouncing people. Whoops.

I taught a class over the last couple of Saturdays and told folks they could send their homework to me at mike@mikepope.com. On Wednesday I got an email from a student telling me that the email address I had handed out wasn't working. (The student had managed to find me via a different channel, thank goodness.) I tried sending an email to the address I'd distributed, and sure enough, back it came.

The keeper of my domain (mikepope.com) is GoDaddy. As part of registering my domain and getting them to manage it, I'd gotten "free email forwarding" for the domain. When someone sends email to the mikepope.com domain (e.g., mike@mikepope.com), the message is forwarded to my other, "real" email addresses.

Some months ago, I started getting a steady volume of messages to my real email addresses that told me an email had bounced, often with the message "invalid recipient address." The strange thing was that these were bounces for emails that I had never sent. This turns out to be a well-known problem—spammers forge a From address on their spam mail (they don't want you to reply, they just want you to click the link in the email they send). Spammers use many, many different forged From addresses in their attempts to get around spam-detection strategies. Apparently the mike@mikepope address had fallen into the hands of just such a spammer.

I did investigate a bit whether there was anything I could do about this; I didn't want my ISP (Comcast) to think I was originating these spam emails. But nothing can be done, so I stopped worrying about getting these oddball bounces. In any event, the volume of these no-recipient bounce messages had tailed off recently, tho I didn't think much about it at the time. (I think I reckoned that Comcast's spam detection was filtering them.)

Then came the incident with the class and the frustrated students, so I had a look. It turns out that I had misunderstood something about how email was handled for mike@mikepope.com. Yes, I've set up forwarding for that address at GoDaddy. However, I also have—I don't know whether I actually intended this or whether it was a feature of my domain hosting—an email account at GoDaddy. And over the last few months, that email account had been filling up with lots and lots of these bounce messages for spammers. In fact, the mailbox had reached capacity. As a result, when students sent me email, they were in turn getting a legitimate bounce message from mike@mikepope.com, which said:

<mike@mikepope.com>
child status 100...The e-mail message could not be delivered because the user's mailfolder is full.

Because I didn't understand that I had an actual mailbox at GoDaddy, this didn't make sense to me at first. But after hacking around in GoDaddy's wretched dashboard, I eventually got to the actual email mailbox that I didn't really grok that I had. The Inbox had hundreds (thousands?) of the spam-related bounce mails, along with a few legitimate emails. Oh and look, a nice red graphic told me I'd reached 100% of my capacity. (GoDaddy's response to this problem was to offer to sell me more space.)

I bulk-cleared the Inbox and Trash and now it all works again. Who knows how many legitimate emails I've missed because they got bounced from mike@mikepope.com and the sender didn't or couldn't try again. Hopefully not many.

Now I have to figure out what to do to prevent this in future. One way would be to monitor this GoDaddy-hosted mailbox. I might also just get rid of the GoDaddy mailbox (and keep just the email forwarding), since as far as I know I don't need it. I hesitate on this latter only because managing anything via the GoDaddy interface is ... not fun and not easy. And I don't want to break the part of the system that does work, namely forwarding. Ah, well—it wouldn't be a real website unless I had to screw with it all the time. :-)

Outlook! Stop sending messages on Ctrl+Enter!

Thu, 10 Jan 2013 18:34:24 GMT

If you're like me and you use Outlook and you're a bit of a sloppy typist, you've probably inadvertently sent messages off by fat-fingering Ctrl+Enter. By default, this keystroke performs a Send operation, and boy, can that be annoying.

Turns out there's an easy fix. (To Outlook, not to your typing.) I got this from someone on the web, I think it was. (Alas, I don't remember, so my apologies to whoever that was.) In Outlook, click File > Options. In the Options dialog box, click the Mail tab, then scroll down to Send messages and uncheck (Ha! Take that!) the option CTRL + ENTER sends a message. Here's a picture:

This works for Outlook 2010 for sure, and probably (?) for Outlook 2007. I can't speak for earlier versions.

Office space

Sat, 05 Jan 2013 12:34:30 GMT

I spent over 17 years at Microsoft, and for most of that time, the company went to extraordinary and expensive lengths to try to give every full-time employee his or her own private office space.[1] The company kept building new buildings, and every office move — and there were many — involved a substantial effort to sort out seating arrangements so that people could both have their own offices and had some reasonable proximity to their colleagues.

The company's focus on office space presumably was based on an implicit acceptance of the idea that people engaged in concerted intellectual work need to be able to work in peace. In the widely read Peopleware, a book from the mid-1980s about managing software projects, authors Tom DeMarco and Timothy Lister addressed the need for this type of space:

Before drawing the plans for its new Santa Teresa facility, IBM violated all industry standards by carefully studying the work habits of those who would occupy the space. [...] Researchers observed the work processes in action in current workspaces and in mock-ups of proposed workspaces. They watched programmers, engineers, quality control workers, and managers go about their normal activities. From their studies, they concluded that a minimum accommodation for the mix of people slated to occupy the new space would be the following:
100 square feet of dedicated space per worker
30 square feet of work surface per person
Noise protection in the form of enclosed offices or six-foot high partitions (they ended up with about half of all professional personnel in enclosed one- and two-person offices)

For a few decades, it seemed that Microsoft was taking this advice to heart. About 5 or so years ago, however, it became evident that the company had changed its mind about space requirements. As buildings were added or remodeled, new layouts were introduced that emphasized open spaces and that featured areas (nicknamed "fishbowls" and the like) that seemed intended to foster interaction: a physical manifestation of the "collaborative workspace." Some years ago, all the technical writers and editors for a major division were moved to a new building and were presented with their new space, which was a cubicle farm (with 4-foot walls) inside an enormous, high-ceilinged open space. Old-timers were horrified.

I moved to Amazon in 2012. The space I'm in is a somewhat curious hybrid of semi-private offices (2 people per) and clusters of cubicles. Aside from obvious seniority/hierarchy, I can't tell exactly how the space is doled out; even as a new employee, I have half of an office. Developers who've been there longer than I have sit across the aisle from me in cubicles. There are open spaces that contain tables and chairs, and I very frequently see one developer or other sitting on a beanbag chair among the cubicles, tapping away on a laptop.

Certainly the space arrangements do encourage the kind of collaborative work that open-space proponents believe in. There's a constant hum of conversation, stand-up meetings, people popping into one another's offices, and so on. Every single person has a laptop, and people carry them everywhere. No one on my team is more than a short walk from my desk, so it's almost as easy to just buttonhole them as it might be to compose an email with a query. And there's absolutely no doubt that the mingling that occurs in offices and hallways and common areas fosters communication; hardly a day passes when I don't have a useful conversation with someone who I just happened to have run into in passing.

This has made me ponder the question of private space versus collaborative space. Were the studies that IBM did incorrect about the need for private space? That doesn't seem likely. Yet all around me I saw people working all day, and clearly getting things done, in an environment that would have made the space designers for the the Santa Teresa facility throw up their hands.

What's different now? Well, here's some speculation.

One obvious difference is that many of the people occupying the cubicles are young, by which I mean considerably younger than I am. (It is one of those milestones of a long career that I now routinely work with people who are about the same age as my children.) To be clear, the average age of software developers has probably not changed significantly in the last 30 years, and I would absolutely not claim that there's something evolutionarily different about youngsters today that somehow makes their brains different or anything like that. I would suggest only that many folks who are developers today did not come up in a corporate environment of private offices, hence are used to working in an open-space plan; it might be the only type of office space they've ever been in.

Another difference is that people today might be more used to creating what we might term "psychic privacy" (as opposed to physical privacy). One thing you do see a lot as you pass cubicles is people wearing headphones, often noise-cancelling models. I can see this as a privacy measure in two ways. One is that it creates an exclusionary environment for the person wearing the headphones, who can tune out the otherwise very close ambient noise. Two is that I for one am less inclined to lean over a cubicle wall and make an inane remark to someone wearing headphones, which is to say, headphones become a signal that someone is in fact trying to work — a kind of metaphorical closed door.[2]

And finally, I think that in some ways things haven't really changed. I was chatting to one of the beanbag-chair-sitting developers not long ago (a serendipitous meeting in the kitchen) and asked him about his ability to sit in the midst of bustling activity and get things done. His answer was instructive: when he has to get real work done, he said — by which he meant serious, heads-down coding — he stays late and works after other folks have gone.

This last, I think, is probably an answer for how to reconcile the IBM findings with the current fashion in open-space design. People do get benefits from open space in terms of collaboration, and then can carve out small niches of privacy in order to encourage flow-type experiences. But they also still hide themselves away when they need physical privacy in order to perform concentrated work. This is made easier also by the portability of laptops, which let people find an environment they prefer and to work there. Many people do work at home, where they presumably have spaces that they've structured for personal productivity, and of course let them work during the hours when they're most productive.

I suppose the conclusion is that if you're IBM in 1982 and you're going to chain developers to a desk so they can work at their non-portable terminals, you'd better give them some private space in which to do that. If they need to collaborate, give them a meeting room. The current environment seems to have essentially turned this on its head: put people together so they can work together, and if they need to, they can slink off and find some private space in which to work on their own.

Even tho I'm old-school, generationally speaking, I don't mind this new environment. Since the beginning of my career I've split my work between collaborative and secluded, with the secluded portion usually done at home late at night. It's certainly become a lot easier to make work portable in the last 30 years. That other people might not find the new space arrangements as conducive as they'd like, however, I can easily see.

More reading:

Collaborative Workspaces: Not All They're Cracked Up to Be. In addition to exploring the potential cons of open-space plans for at least some employees, suggests that one reason corporations like open-space plans is the obvious one: it saves them money.

Programmer Interrupted Chris Parnin goes into a bit of depth about the cognitive costs of interruptions.

Why You Can't Think at Work Jason Fried says that the office is "optimized for interruptions."

[1] Contractors were not generally afforded this luxury, and I saw plenty of one-time conference rooms that had been converted to "contractor bays." And in any event, the company's mad expansion meant that it was logistically impossible to give everyone their own office, and plenty of people had to double up out of necessity. But the ideal at the time was certainly that FTEs should have their own offices.

[2] A couple of people who work in the big cubicle farm at Microsoft have said that the open space has had the paradoxical effect of reducing ambient noise — or at least conversation — because everyone can hear everything.

Sleight of hand

Wed, 02 Jan 2013 19:55:18 GMT

Two stories, both lifted from articles in the New Yorker, about magicians who are, well, magic. The first is about the sleight-of-hand master Ricky Jay, from a profile in 1993 titled Secrets of the Magus:

Deborah Baron, a screenwriter in Los Angeles, where Jay lives, once invited him to a New Year’s Eve dinner party at her home. About a dozen other people attended. Well past midnight, everyone gathered around a coffee table as Jay, at Baron’s request, did closeup card magic. When he had performed several dazzling illusions and seemed ready to retire, a guest named Mort said, “Come on, Ricky. Why don’t you do something truly amazing?”

Baron recalls that at that moment “the look in Ricky’s eyes was, like, ‘Mort—you have just fucked with the wrong person.’ ”

Jay told Mort to name a card, any card. Mort said, “The three of hearts.” After shuffling, Jay gripped the deck in the palm of his right hand and sprung it, cascading all fifty-two cards so that they travelled the length of the table and pelted an open wine bottle.

“O.K., Mort, what was your card again?”

“The three of hearts.”

“Look inside the bottle.”

Mort discovered, curled inside the neck, the three of hearts. The party broke up immediately.

Then this appeared in the current issue in an article about Apollo Robbins, a different kind of magician, titled A Pickpocket’s Tale:

A few years ago, at a Las Vegas convention for magicians, Penn Jillette, of the act Penn and Teller, was introduced to a soft-spoken young man named Apollo Robbins, who has a reputation as a pickpocket of almost supernatural ability. Jillette, who ranks pickpockets, he says, “a few notches below hypnotists on the show-biz totem pole,” was holding court at a table of colleagues, and he asked Robbins for a demonstration, ready to be unimpressed. Robbins demurred, claiming that he felt uncomfortable working in front of other magicians. He pointed out that, since Jillette was wearing only shorts and a sports shirt, he wouldn’t have much to work with.

“Come on,” Jillette said. “Steal something from me.”

Again, Robbins begged off, but he offered to do a trick instead. He instructed Jillette to place a ring that he was wearing on a piece of paper and trace its outline with a pen. By now, a small crowd had gathered. Jillette removed his ring, put it down on the paper, unclipped a pen from his shirt, and leaned forward, preparing to draw. After a moment, he froze and looked up. His face was pale.

“Fuck. You,” he said, and slumped into a chair.

Robbins held up a thin, cylindrical object: the cartridge from Jillette’s pen.

The (lack of) dogs in the night

Sat, 08 Dec 2012 09:25:21 GMT

I get so distracted by things I hear in meetings that I sometimes wonder how I manage to get anything work-related out of them at all. (Perhaps my boss wonders that too, hmm.) Anyway, the other day someone said that we should put a work item on a "dogs not barking" list.

I pondered this while the other participants continued their conversation. I was pretty sure this was new to me. I thought of a possible meaning or two, but didn't feel confident that I had it.

Fortunately, the guy who'd uttered the phrase is friendly enough, so I popped into his office and just asked him outright. "Oh," he said, and kind of laughed. "It's a phrase I picked up around here from management."

He went on to explain that "dogs not barking" refers to looking out for what's not obvious. It's kind of the opposite of the squeaky wheel, was his (anti-?) analogy — in this context, a squeaky wheel is the customer who's complaining loudly about something they need. But what's out there that customers need but we're not hearing about?

His theory was that it derived from a situation where you'd expect dogs to be barking — at a burglar, say — but they're not. There are times, goes the theory, that you should be hearing dogs bark but you're not, and that means trouble.

Anyone else know this phrase?

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]

A lesson (or maybe just observation) is how hard it is to write documentation in a holistic way. It's quite possible that the two topics were created by different writers at different times. Each topic is, as noted, "correct" in a narrow way. It's a real challenge to try to understand the overall customer experience. This is especially true for API/reference documentation, which is focused on a very tiny slice of the whole — a little like writing a dictionary definition and trying to anticipate all the contexts in which people might use a word.

It's a hard problem, but it's one worth trying to solve. In the end, the customer doesn't really care that the 128K limit is "technically correct" or that the topics were written in different contexts, blah-blah. The end result, as we experienced ourselves, is that the customer is confused. And whatever the difficulties of trying to coordinate far-flung pieces of documentation, surely documentation that leaves a customer with worse information than what they started with has to be a big incentive to try.

[1] The limit was set high for a legimitate reason; the only thing I'll say about that is that the 2K to 10K limits are set by business rules, not physical constraints.

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 in the Wikipedia article on Alphabetical Order, or if you happen to have a copy of the Chicago Manual of Style (16th ed), refer to 16.56ff.)

None of the special-case handling, however, addressed the particular situation of our list, which was this: from the perspective of the user looking for a product, the "Amazon" or "AWS" portion of the name is essentially invisible. Users know these products as CloudFront and Glacier and Auto Scaling. (Or in some cases, the products are best known by their initials, like S3 and IAM.)

So we've taken a stab at alphabetizing the list in what might be called "user-oriented name order." You can see the result in the published page. I'm actually curious how people like this and whether they'd agree that the order we've come up with makes more sense.

This week's editorial fun

Sun, 11 Nov 2012 11:06:07 GMT

A collection of editorial curiosities I've seen lately around town. (Sorry for the photo quality; I cannot master my phone camera.)

No comment.

Update 13 Nov 2012:: I just noticed also that they misspelled "indulge," heh.

Parking garage. This was a term I hadn't previously seen, although it's an obvious enough one.

Editors sometimes argue about just how flexible the word only is. It's not this flexible.

This sort of thing is of course not hard to find ...

This made me laugh. First, I'm not quite clear on why there's a separate entry for Saturday. And then there's the edit ...

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 try and lose, here's The Most Interesting Man in the World on this topic:

[source: memegenerator]

A specious take on fuel efficiency

Wed, 10 Oct 2012 08:33:56 GMT

I’ve put a little over 18,000 miles on my motorcycle. The fact that it gets a whopping 53 mpg gives me an entirely unjustified sense of virtue as I pass other vehicles. Still, now and again I’ll consider the nominal fuel savings that I’ve achieved by riding the bike instead of driving my car. And how much might that be?

To keep things simple, I’ll round numbers grossly. I’ll assume 18,000 miles, 50 mpg for the motorcycle, and 25 for my car (which I actually know, because the car’s computer tracks this). So:

18,000 miles at 50 mpg = 360 gallons

Since the bike gets essentially twice the mileage of the car, it’s all very easy. If I'd used the car for the same miles, I would have used 720 gallons. At (assumed) $4/gallon, I’ve "saved" $1440 by riding my motorcvcle (360 x $4 = $1440).

Of course, this is all laughable. Many of the miles I’ve put on the motorcycle are miles I would never have put on the car—i.e., miles driven just for fun. Not to mention that this supposed savings in fuel expenditures doesn't come anywhere near what it cost to buy the bike in the first place, and what it costs to insure and maintain it.

Even so, every time I pass a Prius, I think "neener-neener, I get better mileage than you." And maybe by the time I’ve put 600,000 miles on the bike, it will actually represent a real savings.

Guard cat on duty

Wed, 03 Oct 2012 06:39:27 GMT

I'm working in a new job, and I was surprised not long ago to get an email from one of our senior developers that read something like this:[1]

To: [whole group]
From: [senior developer]
Subject: I love kittens because they're fluffy

This would be one of yer more wtf new-job moments. A few minutes later we got this:

To: [whole group]
From: [senior developer]
Subject: re: I love kittens because they're fluffy

I stepped out of my office for 30 seconds and I was in the office next door!

There was a reasonable explanation for all this, as it turned out, which involved security. Every company has security policies for computer use, of course, and larger companies might have dedicated IT folks who enforce such policies. One way they might enforce policies is to perform security audits of people's workspaces. For example, has someone written their password on a yellow note and stuck it on their monitor? Fail.

Another policy that the security folks might audit is the practice of locking your workstation when you step away from your desk. Obviously, if you walk away from an unlocked machine, anyone can jump on your computer and start hunting around for sensitive information.

Even a vigilant security audit team, however, can't watch everyone every minute. But I happen to work with a bunch of security-minded developers, so a protocol emerged that if they could catch you with your workstation unlocked, you were fair game to have a fluffy-kitten email sent from your computer. Our senior developer guy, in spite of his protestations, had been caught sneakily when he stepped out for the quickest of conversations.

I got filled in on this by another guy in the group (in fact, the guy who'd gotten the drop on the kitty-loving developer). He explained that the group—as I say, a security-minded bunch—had started it as a kind of game in order to help enforce security policy. The remarkable thing, he noted, was that once the kitty emails started, compliance with the rule about locking workstations had gone from around 10% to over 90% in just a few weeks.

Everything about this business amused me, from the kitty theme itself to idea of security enforcement by (mild) peer pressure. And it's certainly effective—you can bet that before I run to the kitchen or step next door for a wee meeting, I make sure that I've locked my computer.

[1] Some details changed for, um, security purposes.

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.

Blogaversary

Wed, 27 Jun 2012 09:26:24 GMT

Just a quick note: this blog is 9 years old today. I started it in 2003 as a kind of example project for a book I was working on.

A few stats:

Entries: 2,268
Words: 701,668 (not counting code)
Comments: 2418
Hits: 1,426,013

Something that's kind of amusing (well, to me) is a page that shows the times of day when I've posted, by hour. It seems, for example, that my most productive blogging time (posting time, anyway) is between 11:00 pm and midnight.

I've been thinking about rewriting the blog pretty much since I started it, what with new and better ASP.NET technologies coming out all the time. Perhaps year 10 will finally see that happen!