mike's web log

Climate change: Where are the editors?

Wed, 20 Jan 2010 18:25:13 GMT

This is for fun. I was reading the article "UN climate report riddled with errors on glaciers", which reports on an IPCC report that has some errors in it. The controversy is mostly around one particular section of the report, a half page in a report that is 838 pages long[1], and which lists some (incorrect) numbers about how quickly glaciers are melting in the Himalayas.

Naturally, this has thrown gas onto the whole climate-change controversy, with skeptics in particular having a field day with the errors.

What I liked about the whole brouhaha, though, was the following. I bet you know why.

"It is a very shoddily written section," said Graham Cogley, a professor of geography and glaciers at Trent University in Peterborough, Canada, who brought the error to everyone's attention. "It wasn't copy-edited properly."

[1] The term "riddled with" in the article title sounds a little extreme to me.

Logical AND -- in English, not programming

Sat, 12 Dec 2009 12:24:37 GMT

In my work, we deal with a lot of uses of the term and that are defined rigorously, speaking in the logical sense. Which is to say, in the programming sense. For example:

If firstTime = True And listCount > 0 Then
  ...
End If

The AND expression here is clear: both conditions must apply in order for the result of the If test to resolve as true.

So that's programming (and formal logic). English syntax is a bit looser. What do you make of a sentence like this?

This property returns true when the HiddenInput attribute is true and the HiddenInputAttribute.DisplayValue property is set to false.

The scope of the word and here is not exactly clear. Does it mean (condensing here):

The property returns true when HiddenInput is true, and it also returns true when DisplayValue is true.

Which would basically make the grammatical and (illogically?) into a logical OR. Or does it mean ...

The property is set to true when both HiddenInput is true and DisplayValue is true.

Meaning that both conditions must be true.

What do you think?

That renumbering problem with Word lists

Tue, 03 Nov 2009 08:46:07 GMT

When I teach Word styles, I make the case that although the features in Word for creating lists are pretty powerful, there's an inherent limit in list styles. There's a useful chart that I found somewhere[1] that shows the kinds of styles that you can create and what attributes you can set for each type of style:

You can see that in the List column, there's no checkmark for paragraph formatting. This is evident if you create a list (as opposed to paragraph) style:

(Multi-level list styles do let you specify a different indentation for each list level, at least.)

If you use the automatic list features of Word (), or if you create a multi-level list style, you end up using a style called List Paragraph. This is technically a paragraph style, and for List Paragraph you can modify the style definition, but frustratingly, any changes you make to paragraph styling, such as indentation or spacing, appear to be ignored.

For quick-and-dirty list formatting (which probably covers most people for most situations), this isn't really a problem. At work, however, we often need to specify interlineal spacing or other paragraph-y formatting, or we need to be able to set different characteristics for different indentation levels.

What we do, and something I tell students they can do if they need this level of control, is not to create a multi-level list style. Instead, go with the approach that olde tyme Word users know -- create a paragraph [more]

Job ad on Facebook

Mon, 14 Sep 2009 10:21:03 GMT

If you're of an editorial disposition, I think this thing writes itself:

The wheels on the car go round and round

Sun, 16 Aug 2009 22:12:56 GMT

There's a post on YouTube of a film made in the 1930s about how the differential in a car works. (The differential is the part of the gearing system that lets the inside and outside wheel of a car turn at different speeds during a turn.)

(If you want to skip the rather lengthy intro involving motorcycle acrobatics, go to 1:50 or thereabouts.)

The film is a good model for what we at work call "overview" topics -- topics that provide a general description of a feature, in contrast to procedural (how-to) topics. Particularly well-done aspects of the film are:

It begins with a clear and simple explanation of what the "problem space" is. More or less by definition, the viewer doesn't know much about differentials, so the first thing to do is to explain why they're necessary.

The film uses the simplest possible model to show how a differential actually works. Their little stick-gear model couldn't be clearer.

They leave out unnecessary detail. The differential that they show at the end is pretty complex, but they don't belabor the details of the how the gear are cut or whatever, beyond a passing comment that this helps with smoothness and with making the differential compact. Good enough for this explanation.

In fact, they repeat these principles throughout -- at each stage, a problem is discussed using a simple demonstration (e.g., the first model would not be smooth enough) and the solution, and again at each stage they focus on only the essentials.

[more]

The technical editor's life

Wed, 12 Aug 2009 17:24:14 GMT

This is the kind of comedy that I go through all the time. Here's a sentence in a document I'm editing:

In order to increase the site density of hosted applications, many hosters run multiple Web applications in a single worker process.

I comment, with respect to the highlighted bit, "Can you explain what this means?"

The author helpfully povides a comment in the document that says: "It is common industry jargon for how many websites can be stuffed onto a single server."

Aha. Do you see what's going to happen here? Observe:

In order to increase the number of Web sites that can be hosted on a single server~~site density of hosted applications~~, many hosters run multiple Web applications in a single worker process.

Conclusions to be drawn:

If your editor questions a term, it really means that the editor thinks the reader won't know it. Don't explain things to the editor, explain them to the reader. (The editor is a reader too!)
If you hear yourself saying (or typing) the term jargon, watch out. The odds of success of defending a term by saying that it's jargon ... not so good.

PS If you're going to comment and say "I know what that means!" I'm going to say "Good for you. Does every reader know what it means?"

BlackhawkDatabase Down

Thu, 06 Aug 2009 22:56:11 GMT

Facebook error message:

My questions:

Does it matter that it's a database error? (Why?)
What's the difference between a temporary error and the other kind?
If the database is down, what good will it do to try again? (please)

And has been noted before, there's something unsatisfactory about clicking Okay under these circumstances. Maybe they should just change the button label to Grrrr.

Looking in the dictionary means you've failed

Tue, 04 Aug 2009 23:20:51 GMT

Being interested in dictionaries is a sort of sign of uber-word-nerd-ness -- what could be considered more word-nerdy than sitting around reading a dictionary? But for those who do, there is no end of amusement. Nancy Friedman has a cool post about dictionaries, which includes a note about some of her favorites. (The Cowboy Dictionary among them, what fun.) One of my favorites is Mrs. Byrne's Dictionary of Unusual, Obscure, and Preposterous Words, or of course the legendary New Hacker's Dictionary, aka the Jargon File. Anu Garg's A.Word.A.Day list, which mines the incredible richness of the English lexicon, has legions of fans.

On the more utilitarian side, we at work have a prescribed list of reference works. For our dictionary, we use the American Heritage Dictionary. Even knowning that the AHD was designed to counter the "permissiveness" of the infamous Webster's Third, I like the AHD a lot.

[more]

Traffic revision

Thu, 30 Jul 2009 11:38:50 GMT

Someone at work just sent this around[1] -- these signs are (apparently) here on campus:

[1] With the comment "So ... which of you was responsible for the last sign on this pole?" Ha.

Two odd sentences

Wed, 22 Jul 2009 23:41:08 GMT

As Judith Tarutz has said, "An unfortunate side effect of editing is that you'll find it difficult to simply read ever again." So you're reading something, and you run across some odd sentence. Most people just bash on and forget about it. But for the unfortunate few, odd sentences nag and just won't go away.

Here are two I ran across in my recent reading about motorcycles. This is from the Motorcycle Operator Manual, put out by the Dept of Licensing of Washington.

Collisions are not rare events — particularly among beginning riders.

I just can't get out of my head the picture of a swarm of beginning riders driving around, running into each other.

Here's another, this from an article (actually, a press release) about a particular type of helmet:

The neon color increases rider conspicuity for increased visibility and safety while riding.

The word conspicuity is, I'll grant you, a bona fide, dictionary-residing word. But really, is that the best possible way to say that the helmet makes a rider conspicuous?

Ok, maybe now that I've blathered about these, I can get them out of my mind. Let's see what tomorrow's reading brings.

This keyboard shortcut requires the mouse

Sun, 17 May 2009 10:19:44 GMT

Bil Simser spots a problem in the Internet Explorer online Help:

I had a look, and this (or similar text) appears in the Help for IE 6, IE7, and IE8. (The example above is from IE 8.)[1]

Simser comments: "Reading this just makes me wonder if anyone proofs this stuff. Fail."

I am hypersensitive to issues like this for a couple of reasons. One is that errors in the documentation annoy people. Even this small error has a disproportionate effect on how the Help system is perceived.

Another issue is that Simser specifically impugns (correctly) editors. This concerns me because the overall trend -- in newspapers, in technical writing, everywhere -- is to get by with less editing. Various reasons are proposed for this, but one of them is that the general quality of writing on the Web has lowered the bar for what people will accept. Perhaps it's true that readers are willing to wade through subexcellent writing on a blog post that addresses a technical issue of particular concern to them. But it seems clear from this one example, anyway, that people continue to have high expectations for the accuracy of official documentation.

Hat tip: Michael B.

[1] It is conceivable that by "click", the Help authors meant "press Enter," which works. If that's so, however, a) it's not clear and b) they do use the word ENTER elsewhere, so this is confusing at best.

Why not link to Wikipedia?

Thu, 07 May 2009 22:07:40 GMT

An issue that has come up a number of times at work is the question of linking to articles in Wikipedia. It's not terribly unusual for us to link from the documentation set to non-Microsoft resources. A common example in my world is linking to the W3C site. For example, in the topic (article) ASP.NET and XHTML, we discuss how we implement (or don't) XHTML standards, but we refer you to the W3C site for actual standards.

Other examples where we've linked to external sites:

The Section 508 site for information about accessibility.
The IANA site for a reference of MIME types.
The Mozilla developer site for information about the document object model (DOM) supported in the Gecko browser rendering engine.
The Unicode site for (duh) information about Unicode.

There are more, but you get the idea. The thought here is that these sites provide information that is not specific to our product but that is useful to our audience. It would be silly for us to copy this info or (god forbid) rewrite it so it could be part of our documentation site.

You will probably note that sites have certain features in common. They are:

Authoritative. Many of our links are to the sites of standards bodies.
Commercially neutral, at least for the purposes for which we are linking. For example, the Mozilla site could be thought of as a competitor to, say, Internet Explorer, but from our perspective (server-based Web coding), it's just another client.
[more]

It's un-, see, and loadable. Get it?

Wed, 18 Mar 2009 17:43:40 GMT
We had another amusing moment today where people who are a little too close to their technology sort of forgot about the English-speaking part of their audience. (Earlier example) To explain this, I have to get slightly technical, but bear with me.[1]

un·load·able
In our world, an assembly is a hunk of code that runs in your computer. It can be loaded "dynamically," which is to say, only when it's needed. However, a slight problem is that once an assembly is loaded, it stays loaded. (This is why you so often have to reboot your computer after updating it -- there are new versions of assemblies that are already loaded, and the only way to get them out of memory is to reboot.)

Ok, so, some of the geniuses we work with have devised a kind of assembly that can be unloaded without having to restart the whole works. What would you call this thing? Well, the current working name for these things is unloadable assembly.

Perhaps you, like us, see a problem here. Is it (to borrow the useful parsing of Colleague Handan) an assembly that is un-loadable or an assembly that is unload-able?

When this duality was pointed out to the writer who was using the term, the writer had a stock answer: "Programmers will understand what we mean." This is a classic writerly cop-out -- "you don't understand it, but my readers will." Uh-huh. Don't count on it.

[1] If you're a technical person, let's not get into a debate about details, ok? They're not relevant here.

3 writing & editing things

Mon, 16 Mar 2009 12:19:11 GMT
If you read the same blogs I do, these won't be news. Otherwise, however, for your pleasure and perusal, three annotated links to some editorially orientated posts.

"Read rage" over manuals. Janet Swisher sums up things that make you go "You suck!", an opinion we get with some regularity in the comments on our docs. Some contributing factors:
online documents with dense paragraphs and poor page navigation
long complex sentences
poorly ordered procedures
missing explanations, such as for product variations, or product handling
instructions that are culturally inappropriate or just plain nonsensical
Yes, my pretties, you know what I'm going to say, don't you? What these people need is editors.

[via Gordon Meyer]

The Subversive Copy Editor. Carol Fisher Saller responds to the thousands of questions that are sent to the Chicago Manual of Style. It might be hard to imagine how a grammar Q&A can be entertaining, but it is; you might have read some of her answers before. (Stet offensive). Saller has collected the insights and wisdom that she exhibits in her answers into a new book. John McIntyre excerpts a few gems, among them the following:
[more]

There's a word for it

Tue, 10 Mar 2009 12:59:26 GMT
In the world of editing, new terms are generally slow to be accepted. There are two reasons for this, namely that editors don't want to release a new term until they are reasonably assured that a) it's not just a fad term and b) most readers will understand it without difficulty. (Well, also because editors in general tend toward the conservative side when it comes to language issues.)

However, in what might be a record for shortest time to acceptance, a debate has begun about whether our corporate style guide should be amended to accept the term netbook. This is still subject to legal review, but it's at least gotten to that stage.[1]

This seems like a pragmatic discussion, because there isn't really a very good alternative term. "Subnotebook"? "Small notebook PC"? These are not bad terms (well, the sub- prefix in the first term is perhaps not precisely defined), but it seems that the current industry term is in fact netbook. Being too conservative in accepting a term like this for our publications can actually lead to confusion ...
Us: "Small notebook PC"
Them: You mean "netbook"?
Us: Yes.
Them: Then why didn't you just say so?
There was discussion at one point about the term podcast, which some people thought (probably correctly) was obviously based on the name iPod, and we therefore had a variety of reasons to avoid using. But again pragmatism made the decision for us -- what other term could you use for podcast, especially if your only reason for using the term is to avoid actually saying podcast?

As I say, it's not a definitive ruling yet, but as I also say, it's been an unusually fast process for proposing the formal acceptance of a new term. Guess we'll see how it all shakes out.

[1] [more]

Newsroom (and tech writing) of the future

Mon, 02 Feb 2009 21:09:56 GMT
Steve Outing writes in Editor & Publisher about what a newspaper might look like after it's gone to an all-digital, no-print format. (I got this from John Osborn, BTW, altho it was via Facebook.) Outing's throught are of course timely. For example, as the Christian Science Monitor reports:
The Christian Science Monitor plans major changes in April 2009 that are expected to make it the first newspaper with a national audience to shift from a daily print format to an online publication that is updated continuously each day.

The changes at the Monitor will include enhancing the content on CSMonitor.com, starting weekly print and daily e-mail editions, and discontinuing the current daily print format.
Other newspapers are for sale, including the Seattle P-I.

Outing envisions a scenario where newspapers look a lot more like content we're already used to on the Web. For example, reporters might file reports in a format that he (or someone) has termed beatblogging.

It's an interesting read. One of the passages that struck me in particular had to do with what types of skills reporters in this all-digital age might need:
[more]

Roundup

Wed, 28 Jan 2009 11:20:19 GMT
You know what I wouldn't mind? A bit of sunshine. Wrong time (winter) in the wrong place (Seattle), I guess.

Fake reviews prompt Belkin apology. I guess I've just always assumed that some number of product reviews (and restaurant reviews) are by shills. (I'm usually most suspicious of the ones with the really, really bad grammar, haha.)

The #1 Song on this Date in History. What was the #1 song on the Billboard chart on the day that you were born? (Me, it was Elvis Presley, "Too Much.") [via Sarah]

What the Web knows about you. Check out the list in the sidebar of all the things the author was able to find about himself. [via ... just about everyone]

Facebook and list mania, aka "25 Things About Editors". John McIntyre's editor-specific take on the "25 things about me" meme that's been going around.

Why editing makes reading hard

Sat, 10 Jan 2009 20:58:50 GMT
It sometimes surprises people, I think, to hear the amount of time it can take to edit something thoroughly. When I'm in serious developmental-editing mode, it might take up to, dunno, 30 minutes to hack my way through a page. (As they say, YMMV.)

Consider the task of just reading a page in a technical book. You read a bit, and you might stop and cogitate as you go. If you're not real clear on what you're reading, you might go back and re-read what you've read, or perhaps you push forward with the hope that it will become clear ar you proceed. This is deliberative reading, and will usually not be quick.

Now consider how the editor reads it. As the editor is reading, they are taking in the text and trying to understand what it says. But at another level, they're constantly comparing what's in front of them with a mental image of how they think it should be. It's a kind of multitasking, reading the actual text and a sort of platonic ideal at the same time.

Of course, at any point where the two "texts" diverge, the editor stops and suggests a fix. They then have to back up and re-read the revised bit, now with altered text being compared against the ideal.

Depending on what level of editing is going on, the scope of the mental model varies. When doing a first ("developmental") edit on a draft, the scope is, effectively, the whole article or paper or even book. As the editor reads, for every bit of text the editor is is asking whether it ...
makes sense.
is saying it (technically) right. (Obviously, this varies by situation, and tech reviewers are more responsible for the correctness of the content.)
is saying everything that needs to be said, but not saying too much.
[more]

Roundup

Tue, 06 Jan 2009 19:02:20 GMT
What kind of person uses a computer to generate their cover letter? At night?

4 Types of Person (a guide to stupidity) Odds are that you're not a Mr. Spock.

The Sky in Motion. Beautiful time-lapse movies of the night sky. [via Friend Steve]

Resolution Randomizer. Let the computer make your resolutions. The text is ok, but the graphics are great. (Requires Silverlight.) [via Brad Abrams]

Cover Letters from Hell. Killian & Company posts excerpts from some of the worst cover letters they've gotten. They observe: "An error-free letter is now so freakin' rare that the minimal care required to send a letter with zero defects, combined with a few crisply written simple declarative sentences, will, alone, guarantee a respectful reading of a résumé." [via Fritinancy]

Which element of style?

Thu, 01 Jan 2009 20:03:16 GMT
Wheresoever you find people who fool around with writing stuff, you will find passionate advocates for The Elements of Style by Strunk and White. Like this:
"The Elements of Style, by Strunk and White, is a must have for all serious writers." [source]

"The Elements of Style (4th Edition) by William Strunk Jr., E.B. White, and Roger Angell makes number one as the best reference book for today’s writer. No matter what edition you get Strunk’s writing reference is a reader that many writers have been advised to read more than once. It’s the bible for writers." [source]

"Although White died in 1985, his little book is still among a writer’s best friends." [source]
So, um, riddle me this: which elements of style have people learned specifically from this book? For folks who keep the book close to hand, as is sometimes claimed, what is it that wants looking up every now and then?

A taste that was bad was left in their mouths

Wed, 10 Dec 2008 19:31:33 GMT
I was listening to NPR tonight, where they were interviewing Jim DeMint, the distinguished senator from South Carolina. They were on about some thing or other to do with car companies, but what really got my attention was how he said something, because the gentleman got himself into a bit of a linguistic pickle. At one point in the interview he came out with:
... left a bad taste in a, uh, a number of members of Congress, uh, mouth.
(This starts right about 3:15 in the interview.)

That is (haha) a mouthful. He hesitates before launching into that gnarly possessive, and dang, you can see why.

Dealing with compound nouns is kind of tricky. For the plural, you inflect the actual noun: members of Congress, fathers-in-law, attorneys general, to call the roll of the usual suspects. Yet the possessive inflection wanders to the end of the compound unit: my father-in-law's car or the attorney generals' conference.

This kinda doesn't make sense. As in, for plural its noun + qualifiers, but for possessive it's all a unit?

The vernacular is, for a change, more consistent: poll a bunch of folks who are not (e.g.) editors and see if you can get them to produce a plural for their in-laws; I guarantee that you'll hear about a great many father-in-laws. (Good luck trying to maneuver someone into spontaneously saying the plural of attorney general.)

The construct that Senator DeMint launched into is probably a no-win situation. If I get this right, a "correct" inflection for all of this would be:
... left a bad taste in a number of members of Congress's mouths.
[more]

Apple style guide

Fri, 14 Nov 2008 17:34:19 GMT
Gordon Meyer links to the latest incarnation of the Apple style guide (PDF). Of course, many of the entries contain familiar advice. (You'd be hard-pressed to find style guides that disagree with much of what's in here.)

Still, I was interested that some of the Apple style recommendations are different than ours at Microsoft (ie, in MSTP). Here are a few examples of where Apple has a different style:
companywide (v company-wide)
dialog (v dialog box)
email (v e-mail, e-mail message)
filename (v file name)
web (v Web)
webpage, website (v Web page, Web site)
I wonder if the Apple recommendations reflect more, you know, modern sensibility about these terms. Time will tell, I suppose.

What tools should a tech writer know?

Fri, 17 Oct 2008 23:09:52 GMT
After class today (about which more anon) I got to talking to a couple of people about tech writing. (These are people who are currently in the certification program at BCC.) One of the topics that came up was what software and tools an aspiring tech writer should be familiar with.

I don't actually have a stock answer to the question (you'd think I would, no?), so I scribbled down a list quickly that consisted of this:
HTML

XML

Microsoft Word

Microsoft Excel
The latter two are of course more-or-less mandatory skills at Microsoft. Word is our primary authoring tool, and Excel is used as a kind of catchall tool for dang near anything -- lists, schedules, you name it. I hear it also can do math. :-)

I also said that I knew of lots of tech-writing shops that use Framemaker, so that seems like a handy tool to know, although (AFAIK) we don't use it at Microsoft.

What might we add to the list? What we're talking about here is stuff we'd expect an applicant to have skilz with already. Not necessarily expert chops (tho that's certainly a plus), but also not just a "I've been looking at a book about this the last couple of days" sorta familiarity.

A few that it occured to me later are:
Windows. As in, we simply assume that people know how to deal with files and Explorer and network access and generally how to move files, install software, and so on. Screamingly obvious, but, you know, maybe not to someone just getting into the tech industry.

Outlook. The lifeblood of Microsoft. (Scott Hanselman: "I swear this freaking company uses Email like it's chat." So true.)

Browsers. Again, we just assume that people know how to navigate the Web and the intranet.
Further thots? What about outside Microsoft?

National Jot and Tittle Day

Wed, 24 Sep 2008 08:53:17 GMT
Today is National Punctuation Day, altho you will probably not find this marked on your calendar, let alone do you get a day off work. (Even the federal government, hahahaha.) Per the Web site of the sponsoring organization (NationalPunctationDay.com, in a chicken-and-egg kinda way[1]), punctuation is important:
Why is punctuation important Jeff Rubin the Punctuation Man and founder of National Punctuation Day explains that without punctuation you would not be able to express your feelings in writing not to mention know when to pause or stop or ask a question or yell at someone and without punctuation you would not be able to separate independent clauses and show an example of how a business lost millions because of an errant comma so dont forget the most important punctuation mark $$$$$$ OK so a dollar signs isnt a punctuation mark but its important dont you agree
All the usual suspects shuffle into the lineup:
Recency Illusion: "Punctuation has been devalued by a generation of computer wizards who ask, ‘What’s the point? Nobody writes in complete sentences anymore.’" (Two for the price of one, actually: not only has punctuation gone to hell recently, but it's specifically computer wizards who are the source of this decline.)

Evils of Texting/IM: "Casual shortcuts bred by e-mailing and text messaging have no place in professional business writing. [...] Careless punctuation mistakes cost time, money, and productivity" (No actual evidence for this is provided.)

The same old anecdotal evidence for the Dangers of Punctuation Mistakes [more]

Grammar? Who gives a sh*t?

Tue, 23 Sep 2008 14:18:54 GMT
The Wired blog had a post today about the new Google phone. These are the first two comments for that post:
This is a very informative article, and I do enjoy reading wired news, but you guys really need to work on your simple grammar. Do you have editors at all?
Posted by: Mike | Sep 23, 2008 10:00:49 AM

Mike. who cares. It's the friggin internet. You got the information. You understood it, right. Or was it too confusing? What is this 8th grade English class. Get over it. They aren't writing text books. Its a blog for crissakes!

People who comment on grammar through blog posts need to find something better to do with themselves.

I am an editor, and I approve this message. Thanks for all the good work Wired.
Posted by: c | Sep 23, 2008 10:19:33 AM
PS The Mike who posted the first comment is not me. :-)