1. Original Entry + Comments2. Write a Comment3. Preview Comment
New comments for this entry are disabled.

October 21, 2011  |  Words (not) to live by  |  7117 hit(s)

John McIntyre has a post today about using evidence to support assertions about language, and I've been thinking anyway recently about the need for empirical support for things like planning your documentation. (More on that another time.) Thus I was primed today while I was editing to think about edits I make that I really can't justify.

The writer David Owen said once that early in his career he interned for someone who "maintains an idiosyncractic but absolute ban on the word however."[1] Every editor has terms — words, phrases — that they just don't like. A word seems ungainly to them, or it violates some bogus rule that the editor once learned, or ... well, whatever. It's subjective, but in each case it's specific to that editor and can't be justified in the usual ways. (Logic, precedence, or appeal to authority.)

So for a little Friday Fun, here's a list of edits I make that have no more justification than "because I don't like it." :-)

Custom Formatting Based Upon Data [#]

The number of times in which I think upon is better than on is so small that I can't remember the last time I let upon stand.

ASP.NET MVC 3 and the @helper syntax within Razor [#]

My ban on within isn't quite as absolute as it is on upon; there are times when it does clarify. (Something like The rule constrains the numbers to those within a specific range.)

desire, desired
Windows Server 2003 ships a new ‘Configure Your Server Wizard’ to help you properly configure your server in the desired mode. [#]
[A]n advanced HTTP handler designed to enable file protection for any file you desire. [#]

I am on a personal mission to stamp out desire in technical docs. C'mon, it's just want. And not just that. My experience is that desired is almost always a way to avoid saying youthe desired mode really just means the mode you want.

wish (as in, any option you wish)

Same as desire, tho my aversion to wish is milder than it is to desire. Just use want, already. Anyway, there are uses I am ok with, like wishlist.

Now let’s run the site. We can start our web-server and try out the site using any of the following. [#]

This one practically makes me froth at the mouth; I mean, my reaction really is irrational. To me, we and let's sound gratingly condescending — I refer to it as "nurse talk" (How are we feeling today?). Obviously most people are just fine with it; practically every tutorial I edit starts off talking about "we" are going to do this or "let's" add a page to "our" website and so on. And the ones I can't get my hands on are out there in the world and people love them. Nonetheless, if I'm given a chance, I discreetly change every we to you and our to your. The only exception I'll make is if the text really is talking about we to mean "we, the authors," as in We have designed this tutorial to show you how to ... or whatever.

There are other such things, tho they're less obvious. No matter how many times Geoff Pullum tells us that which is okay for a restrictive relative (I know this! I agree, even!), I reflexively change it to that. Ditto for only, which has a very free position in sentences, but which I often (again, reflexively) scooch over so that it's closest to the thing it modifies.

So there you have it ... some True Confessions about my editing. You might want to argue with me that some or all of these are just fine, there's no need to edit these things. I would be obliged to agree, as long as I'm being reasonable. The point is, tho, that they just bug me. And I don't think I can be talked out of that.

[1] David Owen, "The Fifth Estate," The Atlantic Monthly, July 1985.

Brian   21 Oct 11 - 1:54 PM

Are we doing the "pet peeves" discussion, then? Because nothing gets under my skin like "utilize." I can't remember the last time I saw the word "utilize" used in any way other than an attempt to find a longer word than "use." Poor "use" -- it's getting shafted just because it's short. You don't "utilize" the dialog box to find a file...you use it. You don't "utilize" inheritance to derive a child class...you use it. And if I see it in a manuscript, I'm going to "utilize" Word's correction tools to change it to "use."

mike   21 Oct 11 - 2:56 PM

> "Are we doing the "pet peeves" discussion, then?"

Yeah, I guess we are. :-)

Kemp   21 Oct 11 - 2:59 PM

I'll throw in "in order to". It's part of the instinct that longer sentences are somehow more professional, so instead of "do X to achieve Y" we end up with "do X in order to achieve Y". A little bit of unnecessary word inflation.

Karla   21 Oct 11 - 4:29 PM

I agree with each of your "bad" words! Most developers write like that for some reason, though. Maybe it has to do with most math professors whose first language isn't American English.

JaAG   22 Oct 11 - 9:22 AM

I marvel at how many of the writers I know (Hi Kemp!) spend as much time writing outside of work as in. Mike's blog is an example. His work and hobbies are the same! I've never been able to get that passionate about writing even though I recognize it as a hugely important part of almost any job. I expect books from each of you in the next five years. I suspect that Mike's could be taken mostly from this blog.