|
|
|
posted at
06:25 PM
|
trackback
|
|
link
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."
[categories]
editing
|
posted at
12:24 PM
|
trackback
|
|
link
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?
[categories]
writing, editing
|
posted at
08:46 AM
|
trackback
|
|
link
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 style that has all the character and (especially) paragraph formatting you need, and that also has numbering or bullet formatting. This gives you complete control over the paragraph aspects of the list items.
As it happens, in Word 2007, the default template already contains paragraph styles that are designed this way -- these are called List Bullet through List Bullet 5, List Number through List Number 5, and List Continue through List Continue 5[2]:
You can see from the style definition for List Number that it's a paragraph style + numbering:
So, when you want a numbered or bulleted list, instead of clicking the bullet or numbering buttons in the toolbar, you can apply one of these paragraph + numbering styles. This works just fine:
Unless it doesn't. The classic problem is this: you change the paragraph formatting of a paragraph+numbering style. For example, you change the indentation to be .5 inches. All seems well initially -- you apply the style to a list, as usual, and it appears to work great. (Notice that the list is now indented.)
But if you try to renumber the list, things to wonky:
The paragraph to which you have applied the customized style reverts to its default paragraph formatting. This is, mmm, annoying.
The explanation appears to lie in how Word applies styles. The following diagram[3] shows the precedence rules for styles. Note that numbering styles are applied after paragraph styles.
What seems to be happening is that Word is indeed applying the (customized) paragraph style, but when it then gets to numbering (since you renumbered, after all), Word applies both the numbering and the default formatting for a numbered list, and the default numbered-list formatting overrides (overwrites) the paragraph formatting that you want.
You can fix this, it seems. What it boils down to is that in addition to specifying your custom paragraph formatting (in the example, a custom indentation), you also specify a custom numbering style:
[Show numbering formatting]
Then when you renumber a list that uses this customimzed paragraph style, the renumbering won't also reformat the paragraph in surprising ways:
I'm not sure how official a fix this is. As in, is this how it's designed? It feels hacky and it might be leveraging specific but not necessarily intentional behavior on the part of Word. But it's worked for me.
Coming soon: a video version of this whole post!
[categories]
writing, editing, technology
|
Monday, 14 September 2009
|
Job ad on Facebook
posted at
10:21 AM
|
trackback
|
|
link
[categories]
editing
|
posted at
10:12 PM
|
trackback
|
|
link
(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.
There are a couple of things about the film that, if I were editing this as a piece of documentation, I would suggest altering. One is the lengthy and essentially irrelevant (tho entertaining) introduction with the motorcycles. The other is the veer off into marketing at the end; it's arguable that understanding how differentials work does not require further discussion of Chevrolet's clever way to install them in cars. Then again, it is a Chevrolet marketing film, so it's not entirely surprising to get some product plugs in there.
Hat tip: Gordon Meyer.
[categories]
writing, editing
|
Wednesday, 12 August 2009
|
The technical editor's life
posted at
05:24 PM
|
trackback
|
|
link
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 serversite 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?"
[categories]
writing, editing
|
Thursday, 6 August 2009
|
BlackhawkDatabase Down
posted at
10:56 PM
|
trackback
|
|
link
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.
[categories]
technology, writing, editing
|
posted at
11:20 PM
|
trackback
|
|
link
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.
 But as much as I like dictionaries, in the context of work, I hardly ever open one. In fact, I cannot recall when I last used a dictionary at work to ascertain the definition of a term that came up in documentation that we were writing.
Does this seem odd? Well, consider. My writing colleagues and I are (almost) all native speakers of English, all educated to college level. Which is to say, we have a pretty decent mastery of the basic vocabulary of English. Sure, there are many words that we don't know, and I'm sure that between us all, we can find many words that we think we know the definitions of but don't.
So here's the thing: if well-educated native speakers aren't 100% clear on the definition of a word, should we be putting that word into the documentation? It's not whether we, the writing team, can figure out the word -- it's whether our readers know it. And while the majority of our readers are also probably college-educated native speakers, we are also writing for people who read English as a second language.
We're not doing anyone any favors if we use terms that send ESL readers, let alone native speakers, off to the dictionary. People already don't want to read documentation. If we throw terms at them that they have to go look up, is this helping anyone?
Now and again our corporate style guide indirectly acknowledges this. Take the example of to comprise, a term that people often get confused. Sure, you could look it up in the dictionary. Here's what MSTP says:comprise
Avoid in general, mostly because its meaning is often confused. It means "include" or "contain." Depending on your meaning, use those terms or consist of or make up as appropriate. Do not use comprised of. In other words, it's not a matter of being technically, dictionary-says-so corrrect. It's a matter of writing to avoid confusion.
Of course, we use a ton of technical vocabulary. But for the most part, we take responsibility for that: if we throw around terms like manifest or boxing or common language runtime (CLR), we'll define the term and give you a glossary that you can use to look things up.[1]
But what we don't do is use the dictionary to verify some fine shade of meaning, or to justify our use of an obscure term, or even to see whether some highly technical term happens to appear in AHD. In any of these situations, if we have to go to the dictionary, so will users. And if they have to, we lose.
[categories]
language, writing, editing
|
Thursday, 30 July 2009
|
Traffic revision
posted at
11:38 AM
|
trackback
|
|
link
[categories]
editing
|
Wednesday, 22 July 2009
|
Two odd sentences
posted at
11:41 PM
|
trackback
|
|
link
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.
[categories]
editing
|
|
|
|
