Friday, 19 September 2014
One of the delights of my job has always been the chance to work with people from all over, and I mean, like, from all over the globe. A nice side effect is that people bring their unique brands of English with them, affording endless opportunities to listen to, read, and think about the vast dialectal variations in our language.
One of our developers has the task of sending out a biweekly email with tips and tricks about using our tools. He happens to be from Sri Lanka, so his English is primarily informed by British usage, and the subject line of his email read “Tip of the Fortnight.” Apparently having second thoughts after the email went out, he popped into my office and asked “Will people understand the term fortnight?”
I think it’s safe to say that literate Americans understand fortnight just fine. But it’s not a term that many Americans produce, I think. I lived in England for a couple of years, and I got very used to expressions like a fortnight’s holiday, but even with this exposure, the term never entered my active vocabulary.
His question, tho, sent me on a bit of a quest to try to determine what the, you know, isogloss is for fortnight. Right across the hall from me is a Canadian, so I asked him. Nope, he said, they don’t use it. My wife has cousins in Australia, so I sent a query off to one of them. Oh, yes, they use it all the time, she said. In fact, she asked, what do you say in the States when you're referring to something on a two-weekly basis? Good question, which underscored why fortnight is such a handy word. I mean, really: how do you phrase "Tip of the Fortnight" in American English?
The word has a long history—according to the OED, it goes back to Old English (first cite 1000), and if I read their note right, Tacitus referred to a Germanic way of reckoning time by nights. (Interestingly, the most recent cite in the OED is for 1879, not that they really needed a cite more recent than that for a term that is in everyday use in Britain.)
I looked in a couple of dictionaries, but neither of them indicated anything along the lines of “chiefly Br.”, as they occasionally will with a regional term. The two usage guides I have handy, Garner and the MWDEU, are both silent on the term. (I slightly expected Garner to comment on the term’s use in, say, legal writing, but nope.)
But I’ll stick to my now-anecdotally based theory that fortnight is just not used much in North American English. Still, I don’t think my colleague had much to worry about regarding the subject line of his email. As I say, I’m pretty sure that my American and Canadian colleagues recognize the term. And of course, many others come from places where it’s a perfectly normal word, and like the cousin, they might wonder why we don't adopt such an obviously useful term.
Wednesday, 17 September 2014
I have a Tumblr blog where I stash interesting (to me) quotes and citations that I've run across in my readings. Tumblr has some nice features, including a queue that lets you schedule a posting for "next Tuesday" or a date and time that you pick.
Tumblr WoesHowever, Tumblr’s search feature is virtually useless, which I sorely miss when I want to find something I posted in the distant past. As near as I can tell, their search looks only for tags, and even then (again, AFAICT) it doesn't scope the search to just one (my) blog.
In theory, I can display the blog and use the browser's Ctrl+F search to look for words. Tumblr supports infinite scroll, but, arg, in such a way that Ctrl+F searches cannot find posts that I can plainly see right in the browser.
When search proved useless, I thought I might be able to download all my posts and then search them locally. However, and again AFAICT, Tumblr has no native support for exporting your posts. There once was a utility/website that someone had built that allowed you to export your blog, but it's disappeared.
APIs to the RescueHowever, Tumblr does support a nice RESTful API. Since I've been poking around a bit with Python, it seemed like an interesting project to write a Python script to make up for these Tumblr deficiencies. I initially thought I'd write a search script, but I ended up writing a script to export my particular blog to an HTML file, which actually solves both of my frustrations—search and export/backup.
Like other companies, Tumblr requires you to register your application (e.g. "mike's Tumblr search") and in exchange they give you an OAuth key that consists of a "consumer key" and a "secret key." You use these keys (most of the time) to establish your bona fides to Tumblr when you make requests using the API.
(Side note: They basically have three levels of auth. Some APIs require no key; some require just the secret key; and some require that you use the Tumblr keys in conjunction with OAuth to get a temporary access key. This initially puzzled me, but it soon became clear that their authentication/authorization levels correspond with how public the information is that you want to work with. To get completely public info, like the blog avatar, requires no auth. In contrast, using the API to post to the blog or edit a post requires full-on OAuth.)
Tasks I Needed to PerformThe mechanics of what I wanted to do—namely, get all the posts—are trivially easy. For example, to get a list of posts of type "text" (more on that in a moment), you do this:
This returns 20 posts' worth of information in a JSON block that's well documented, and which includes paging markers so that you can get the next 20 posts, etc. In a narrow sense, all I needed to do was to issue a request in a loop to get the blog posts page by page, concatenate everything together, and write it out. I’d then have a “backup”—or at least a copy, even if it was a big ol’ JSON mess—of my entries, and these would be somewhat searchable.
As it happens, you use different queries to get types of posts. Tumblr supports a half dozen types of posts—text, quote, link, answer, video, audio, photo, chat. Each type requires a separate query, and each returns a slightly different block of JSON. For just basic read-and-dump, it’s a matter of looping through again, but this time with a slightly different query.
So that’s the basics. As noted, I got this idea that I wanted to build an HTML page out of my posts, and that complicated things. But not too terribly much. (I’m using Python, after all, haha). More on that soon.
Saturday, 6 September 2014
Let's start with bump. Among its definitions is "raise" or "rise," along these lines:There is some subtlety here to the definition; there's connotation of a non-linear increase, as a bump might appear on a graph.
Anyway, by this definition, if something increases in speed, that would be a … speed bump, right? That's how the author of an article in Ars Technica intended it:
The Web is going to get faster in the very near future. And sadly, this is rare enough to be news.Except ... not. A speed bump performs precisely the opposite: it's a device designed specifically to reduce speed. (On a recent trip to Costa Rica, we learned that a speed bump there is referred to as a reductor de velocidad, an admirably straightforward term.)
The speed bump won't be because our devices are getting faster, but they are. It won't be because some giant company created something great, though they probably have. […]
Obviously, if you back up and read the sentence again, you get the intent. And perhaps the term speed bump in its traffic-calming sense isn't known as widely as I imagine, and therefore would not cause many people to, um, slow down. But a simple edit—e.g., "The bump in speed"—would have fixed this small ambiguity.
It never hurts to have someone else read through your text. You never know when their slightly different understanding of the world will send them off in the wrong direction based on what you've written.
And now, back to actually reading the article, which is actually quite fascinating.
Tuesday, 2 September 2014
One kind of writing error (I am tempted to put that into quotation marks) that editors catch is the so-called dangling modifier. In this construction, a modifying phrase appears, on close inspection, to have no antecedent. Here's an example:
Walking up the driveway, the flowers looked beautiful.The dangling aspect is this: who is it that's walking up the driveway? IOW, what does "Walking up the driveway" actually modify? It sure isn't the flowers.
Once you're attuned to dangling modifiers, you'll find them everywhere. For example, I hear them in radio ads all the time. Not long ago, I found this example on a poster in our bus station that was advertising Montana tourism:
(In case you can't read it, it says "As a kid the Mission Mountains were my backyard.")
And that's just the thing: dangling modifiers are quite common. Merriam-Webster's Dictionary of English Usage has a whole slew of examples that go back to the 17th century. Under most circumstances, listeners or readers seem to have no trouble mentally filling in the missing antecedent from context. Indeed, MWDEU observes that "... they may hardly be noticeable except to the practicing rhetorician or usage expert." That's certainly been my experience as an editor—I've not only had to point our dangling modifiers to writers, but I've often had to go through the exercise of explaining why they're (nominally) wrong, as I've done here.
But sometimes opening modifiers do sow confusion. I was reading a movie review by David Denby in The New Yorker today and was taken aback by a dangler. The movie concerns two men (Steve Coogan and Rob Brydon) who are touring around Italy in a car. Here's the sentence that struck me:
Ogling the scenery in "The Trip to Italy," you wonder if the men's small car—a Mini Cooper—will drive off the edge of a cliff, or if, when they board a yacht in the Golfo dei Poeti, someone will fall overboard and drown.Who exactly is doing the ogling here? The nearest noun (well, pronoun) is "you." Am I doing the ogling? The next available noun is "the men's car," which is not likely to be ogling. Is it maybe "the men" (only making a brief appearance in the genitive) or maybe just "they" (which does appear as a subject in one of the clauses) who are ogling?
Perhaps I'm making too much of this, and Denby really does mean me-the-viewer. But the whole sentence—or the opening modifier, anyway—threw me enough that I had to stop and think about it for a considerable time. And another editorial rule suggests that if your readers have to stop and think, the sentence isn't working.
Wednesday, 23 July 2014
I share an office with a fellow writer—let's call him Colleague B. We work on the same team, and thus we do joint planning and work and reporting. For example, every Monday afternoon we have a look at the upcoming week and plan our work. And on Fridays, we put together a joint status report that rolls up all the things we actually worked on.
The nature of our work, however, adds a certain chaos factor to our planning. On Mondays, we can certainly attempt to plan out what we need to do for the week. But every day—literally every day, and sometimes more than once a day—something new pops up. People send us email requesting a review of some documentation, or a developer will stick his head in the office and want input on some UI, or a bug will come in from a customer, or ... well, the possibilities are wide and varied, but there's always something.
Now, Colleague B is, by his free admission, a bit OCD. He is consistent and orderly both about our planning and our reporting, and he has that thing where he intuitively understands the delta between today and some upcoming date. Me, I'm a bit more on the other side, and my sense of time and dates is referred to around our household as "magical thinking."
Colleague B is not a big fan of the daily dose of chaos. Here we've planned out our week on Monday, and people keep coming in and asking for stuff. As he says, in his ideal world, people who have something for us would get in line, and we'll get to them when we're done with what we're working on.
On the other hand, I don't mind nearly as much the drop-what-you're-doing interruptions. I'm apparently happy to put aside the thing I'm working on in order to work on this new thing, or at least, till some other yet newer request comes in.
The world of computers has an analog for us: Colleague B is FIFO: first in, first out. Take a number, and we'll service you in order. In computing terms, FIFO describes a queue. Me, I'm LIFO: last in, first out. Like stacking trays in a cafeteria—the last on the stack is the first one off, and indeed, in computing terms, LIFO describes a stack.
Happily, it turns out that this combination of work styles works out well. Colleague B works his way through our Monday list, odds are good that by Friday, items can be checked off. But at the same time, we've handled a half dozen or so new jobs that came up during the week, things we had no idea about on Monday. In fact, Colleague B says that occasionally he'll finish up something and go read email, and by the time he's become aware of some new request, I've already handled it.
Of course, there's a certain amount of literary license here. It's not as if Colleague B won't handle ad-hoc queries with alacrity, and it's not as if I'm unable to handle anything other than whatever the most recent emergency is. Still, programmers know that sometimes the right data structure is a queue and sometimes it's a stack. As long as there are two of us, and as long as we divvy up the work correctly, we can handle pretty much all of it.
Thursday, 17 July 2014
As has been discussed at great length over the years, English has no gender-neutral way to use a pronoun for a singular and sexed thing:
Everyone should bring [his|his or her] own lunch.
In previous eras, people didn't really blink at using the masculine generically:
To each his own.
... and some still maintain that this is fine, although the insistence that his in such contexts is gender-neutral is easily shown to be questionable:
A nurse is expected to provide his own stethoscope.
Anyway, vernacular English has solved this problem for centuries (like, at least as far back as Shakespeare) by using so-called singular they:
Everyone should bring their own lunch.
Still, as widely used as singular they has been, proscriptions on it have been strong for formal writing. Garner doesn't like it, tho he allows that they is sometimes the "most convenient solution" and that using the singular in some cases can result in "deranged" sentences. Seemingly falling for the Recency Illusion, Garner says that "they has increasingly moved toward singular senses," and "nothing that a grammarian says will change [these developments]."
Chicago 16 is pretty clear: "Although they and their have become common in informal usage [Recency Illusion again?--M], neither is considered acceptable in formal writing." Our own style guide at work: "Avoid using they or them to refer to a singular noun of indeterminate sex. You can usually accomplish this by changing the noun to a plural. In other cases, you can rewrite a sentence to avoid the need for a pronoun altogether."
This last indicates to me how strong the proscription is—rather than take the chance of using a vernacular usage, you write around the need for a pronoun altogether.
Anyway, all of this came to my mind again when I saw an article today about poets, a group known to consist of both male- and female-type people. Observe this interesting struggle by the author:
If you’ve ever been to a poetry reading, the following scene will be familiar. After being introduced, a poet steps onstage and engages the audience with some light social speech. Maybe they* talk about their forthcoming book, [...]Take note of the asterisk, which leads to the following footnote:
* I'm using "they" as the singular gender-neutral pronoun here to avoid suggesting that "Poet Voice" is a gendered thing (it's not), and also to avoid the clunkiness of "his or her."This strikes me as an interesting development. Garner often labels entries in his usage guide using the following index:
Stage 1: New form/innovation used by a small number of users.
Stage 2: Vernacular for speech, not acceptable in standard usage.
Stage 3: Commonplace but avoided in careful usage.
Stage 4: Virtually universally used but still decried by SNOOTs.
Stage 5: Universal.
The article seems like evidence that singular they is hovering somewhere between stages 2 and 3.
The question is how many people would really notice the use of they here if the author had not gone to such pains to point it out. Are we really at Stage 3 or 3-1/2? John McIntyre, who knows a thing or two about copyediting, advises singular they, to which one of his commenters says "A year or two ago I gave in and started using 'they' in the singular. What a relief! It's easy to use and only occasionally sounds awkward. There's no going back for me now."
Friday, 11 July 2014
The default color for a lot of devices is, it seems, black. I can look up from where I'm typing and spot these items in black: monitors (3), keyboards (2), USB hub, computer speakers, mouses/mice (2), laptop, external hard disks (2), modem, router, TV, remotes (3), Roku device, cellphone, chargers, almost all cords, headphones. Not everything is black, but that certainly seems to be ... popular.
It's, what, elegant, I suppose, but it has its downsides. Whenever I'm rooting around in the dark recesses of my backpack for my mouse (black) or bag o' connectors (black) or earbuds (black), I find the near invisibility of these items somewhat inconvenient. However, I accidentally made a discovery that has begun to change my life, so it's got me thinking about this mania for black.
After I got my most recent phone, I was looking for a one of those protective silicone jackets for it. I found one at a kiosk at the mall, but the girl was apologetic: sorry, the only color we have is red. Oh, well, I thought, I can live with that.
And boy, can I ever. With its bright-red cover, my phone now is quite visible. Indeed, I never have trouble finding it, even if I've carelessly left it on our (green) couch or if it's ended up in the passenger footwell of the car.
A guy I used to work with is a big fan of the classic Moleskine notebooks and carries a couple of them everywhere—one for work notes, one for personal notes. After I'd had my epiphany about the red phone cover, I noticed that one of his notebooks was black, the other red. When I asked him about it, he had a similar story: they'd been out of black, so he got a red one, and that had actually worked out well, since not only could he distinguish his notebooks, but he had a lot less trouble finding them.
Since then, I've gone out of my way to look for bright colors. When I ordered a Kindle Paperweight (black, of course), I ordered an orangey-red (!) leather cover for it. I never, ever have trouble finding it in my backpack, by the bedside, or halfway under the couch when I've fallen asleep reading.
My phone and Kindle
I can probably continue to work fine with my black keyboards and monitors, but if I could paint the TV remotes, I would definitely do that. Yes, I think my life us going to be a lot more colorful in my future.
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?
Tuesday, 13 May 2014
Because I apparently don't have enough to do, gah, I took a notion recently to make updates to this blog. I had seen something somewhere about Google Fonts, which made me think about updating the typeface from the venerable Verdana that the blog has sported for the last 10 years.
Making that change required messing about in the blog's stylesheet, and that got me to wondering about the ungodly awful table-based layout that I threw together 11 years ago. I experimented a bit with a 2-column, div-based layout until I got something reasonable working.
If you have feedback, by all means, leave me a comment.
And here it is. I only played with the main page, and I still need to do a lot of weeding and pruning in the style sheet. There's no real effect for readers, I don't think. As with the whole blog project from the beginning, it's all just been about me learning about web development ...
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.