Writer I Am

2012-01-29T12:39:00.001-06:00

I have moved all of my posts over to WordPress to my domain on grammarparrot.com.

What's Happening to "affected"?

2011-08-29T07:28:00.005-05:00

(This is a first draft. I'll come back later and edit, but I wanted to get this out of my head so that I could get on with my day.)

Listening to the news coverage of Hurricane Irene is giving me a headache:
"Sports Events Impacted by Irene"
"Business Impacted by Irene"
"updates from governors and emergency managers in impacted areas"
"travel impacted by Irene"
"millions could be impacted by Irene"
"How you can help turtles impacted by Irene"

I was taught that wisdom teeth can be impacted and meteorites can impact the Earth, but people are "affected."

I think the problem comes from people's confusion over "affected" and "effected." (To review the difference, see http://writeriam.blogspot.com/2009/11/review-of-american-english-grammar.html.) Just like "who" and "whom," no one is going to convince native English speakers that there is a difference between impacted and affected. And even the Chicago Manual of Style says that it's OK to use impacted in this way. When it comes to informal speech or writing, pretty much anything goes, as long as your audience understands you. But formal writing is different. My definition of formal writing includes user guides, journals and newspapers, white papers, really any sort of business writing, and certainly academic writing.

According to most dictionaries, "impact" is a stronger word than "affect," indicating "strike forcefully" (as in a meteorite) or to "fix firmly by packing or wedging" (as when a molar is unable to breach the gum surface). But they also list the definition "to have a direct effect or impact on" which is how most news sources and marketing writers use it. (Really? "Impact" means to have an "impact"?)

My main complaint with using impact(ed) in place of affect(ed) is that it is over used. While watching the news this morning, a reporter was describing an area affected by Hurricane Irene. She used impact and impacted in almost every sentence. At least change it up a bit and use different words to make it less grating on the ears. Well, my ears.

I know I'm unusual. When I write or edit for my job, I try to remove most of the instances of impact, simply because it sounds/reads bad if you use the same word over and over (unless you're writing poetry or songs). Here's an example of academic writing that overuses the word, from http://sciencepolicy.colorado.edu/socasp/weather1/pielke.html

Most people wouldn't notice that and couldn't care less. However, when I read writing like the example above, the message is lost on me, because I'm focused on what I would consider to be errors.

You know how sometimes you're reading something and you stop, then read it again, and maybe again, before you can understand what the writer is trying to say? That's noise. When you write or edit, your mission is to generate a message that is clear and concise and has no noise that would distract your readers from the message. Impact screams out at me from the page, radio, or TV so loudly that I have forgotten what the story was about.

Creating an Hourly Reminder in Windows

2011-07-28T21:11:00.006-05:00

Did you know that someone was actually paid to research and discover the fact that women blink twice as often as men! I don't think any technical writers were in that study. As a technical writer, I sit at a desk all day, rarely having the occasion to move anything but my head, eyes, hands, and arms. When I'm really focusing on something, I even forget to blink! I have alternating "runny" and dry, tired, red eyes.

I decided I need a reminder to stop working, stand up, move around—and blink! Microsoft Outlook does not have a way to set hourly reminders, but you can click Snooze > 1 hour each time a reminder appears; however, I'm more likely to click Dismiss. I didn't want to bring an egg timer to work and have a loud DING go off every hour (I work in a cubicle). And if I set my phone alarm to go off every hour, that would be just as annoying to those around me. (If I set the alarm on "vibrate only," I would probably assume it was a text message and ignore it.)

After some Googling (and finding some unhelpful advice to install a free program—on my work computer), I discovered a sane and doable solution: Windows Task Scheduler!

Using Task Scheduler, I created a task to pop up a reminder message every hour. Task Scheduler allows me to define the text that appears in the message box, when to start the task, when to finish the task, and how often to pop up the reminder.
I've provided the instructions below (Windows 7) for my fellow zombie cubicle ranchers. You need the proper privileges on the computer, of course.

To create an hourly reminder in Windows Task Scheduler

Click Start, then in the search box type Schedule Tasks. (It will probably appear just by typing Sch.)
In the list of programs, click Schedule Tasks. The Task Scheduler appears.
In the Actions (right) pane, click Create Basic Task.

Create a Basic Task Wizard

Type a Name and Description for the task, then click Next. The Daily page of the wizard appears.
Specify when the task it to Start and how frequently you want the task to Recur, then click Next. The Action page of the wizard appears.
Click Display a message, then click Next. The Display a Message page of the wizard appears.
Provide the Title and the Message that you want to appear on the message box, then click Next. The Summary page of the wizard appears. The Summary page displays the details of the task.
Select the Open the Properties check box, then click Finish.
Click the Triggers tab.

In the Start boxes, set the date (if different from today) and the time. I set mine at 9 am.
In the Advanced settings area, select the Repeat task every check box and set it to 1 hour.
Click OK.
Click OK again to complete the task. The new task appears in the list of tasks in the center pane of the Task Scheduler.

After you've created the task, you can make changes to it, test it, disable it, or delete it.
To edit, disable or delete the task

Open the Task Scheduler.
In the Active Tasks area, double click the task. A list of active tasks appears.
Right-click the task, then click the action that you want to perform:

Run—Allows you to run the task to ensure that it is working the way you want it (instead of waiting for the clock to run out).
End—This stops a task that is in progress. Won't need it for timed tasks like this one.
Disable—Prevents the task from running until you enable it. (If you right-click a disabled task, this option changes to Enable.
Export—Allows you to save the task to a file, and then you can import it into another computer.
Properties—Opens a Properties dialog in which you can edit the task.
Delete—Permanently removes the task from the Scheduler.

And there you have it—an hourly reminder! Every hour on the hour a message pops up to remind me to get up and move!

Surviving College Past the Second Year

2011-06-04T18:56:00.001-05:00

This was a "Note" I posted on Facebook but decided to move it here so that my blog looks less sparse.
-------------------
Update, June 4, 2011

He survived his second year--yay! Home for the summer and working/going to summer school. Good to have at least one motivated child!
------------------

My son is in his second year of college at A&M. The second year seems to be the most challenging--that's when Son#1 gave up and came back home. A lot of people that age are going through the same thing, so I thought I would write about my "college experience" (20 years in the making!). (This is the condensed version. I could write a novel series about it!)

I know you hate to hear "when I was a kid" but here it is anyway. When I was in high school, I wanted to be a translator at the UN. I did very well in Spanish (although you wouldn't know it now) and thought it would be fun (except for the living in NYC part). My parents refused to pay for my college--girls who grew up in the 70s were supposed to get married and have babies, not careers!--so I joined the Air Force. In my senior year of high school, I worked as a janitor in one of the buildings downtown, and I cleaned the computer floor. At that time, computers were big behemoths ("main frames") with keypunch cards, mag tape units, teletype machines, and huge hard drives called "RapidAccess Disk" or RAD, as big as a stove! (RAM was cabinets and cabinets full of cards with wire-wrapped magnets!) I often talked to the computer people on the floor who always worked late, so when I talked to the AF recruiter and he asked me what I wanted to do, I said, "Something with computers." So I went to AF tech school to be a "digital flight simulator specialist" which is basically an electronic technician. I worked on the FB-111A simulator which was controlled by a 3 mainframe computers. Very fun job to have, because I also got to "fly" the simulator. I had to fly it to replicate whatever problem the pilot had written up. (e.g., if he said, "The BDHI sticks at flight level 3000 when I turn to heading 230," I had to "take off," go to 30,000 feet, and then turn to heading 230. Then fix whatever I thought the problem was, and try it again.) When I got out of the Air Force, I got a job at Hughes Aircraft working on a Navy system installed on aircraft carriers--which is how I met Bill. He worked on the same system. (They called us when the sailors couldn't fix it--HA HA!) So, naturally, when I went to college, I thought getting a degree in Electrical Engineering or Computer Science would make sense, right? Every semester while I was in the AF, I was also in college, taking a class here and a class there--and letting them pay for 80% of the tuition. I got my general AA degree from UNH and an AAS in Training Devices (electronics and flight systems) from CCAF. But getting a BSEE meant a lot of math--PAST Calculus 3, etc. I had no problem with electronic circuits, binary/octal/hex, computer stuff, and doing the math if I had the formula written down, but I did have a problem remembering the formulas. I gave up and switched majors from BSEE, to BSCS, to BS Chemistry (I thought Environmental Engineering would be awesome), back to BSEE, then finally BA Communication. (BA, because I no longer needed math or science.) I also no longer needed any electives, because I had twice the credits I needed for my degree.

So what I'm saying is that MANY people change majors more than once. You just have to take the undergrad classes that can apply to about any degree, and hopefully during that time something will pop out at you that you'd really like to do for a career. For me it was writing--and I'm still doing "something with computers"!!

Why does documentation "suck"?

2011-05-25T17:45:00.004-05:00

One of my tasks for slow periods at work is to troll the User Forum to read what our customers are having problems with. Each time we release a new version, there are plenty of posts to keep me busy. If I had any sort of ego, I would be severely depressed reading some of the posts that say "the documentation sucks"! OK, it doesn't happen often, but it happens. And almost every time I read or hear that, I can point the complainer to the exact topic that they didn't bother to read before stating that the documentation sucks. Yeah, you are correct—the search sucks. It's not Google search. And yes, when you call tech support, we have a great group of guys who can hold your hand as you walk through the tedious process of creating a chained certificate. But before you blame the documentation, at least make an attempt to read it. All of it! Scroll through the Contents or Index, or type text in the help's Search box (NOT GOOGLE) and press ENTER. That word got no results? Try another one! Read a few results to maybe clue you in to what words you should be using. Try those words. Read a few topics. You might learn something. You won't waste your time, because next time you have a problem, you might need that exact information.

Why does documentation "always suck"? Below are several reasons:

8) Too many cooks in the kitchen. You've hired a technical writer who is both technical and a writer (yeah, doesn't always work that way), and yet everyone wants to tell her how to write. Let her write it. She knows end-users better than you think and has experience writing to that audience.

7) Several different locations are available from which the end user tries to get help: in the application, online, PDF, knowledgebase, user forum…and that's just the locations we can control! Something is bound to get lost in the shuffle—or too much salt added to the soup, to continue the “cooks” cliché.

6) Companies like to save money. Why would they hire a highly-paid programmer to spend his day writing documentation? And if he's a programmer, why would he want to? Besides, developers tend to be very advanced in their field and talk way over the customer's head. (“Everyone knows that!”) The customer wants to know "what grade of oil should I use in my car this winter?" not "how does the internal combustion engine work?" (Note: I have met programmers who write very well to an end-user audience. But they are rare. Many write "to please the teacher" rather than to have their communication understood.)

5) Companies like to save money. They are likely to hire "Bob's cousin, Milly who's really good with Word" as their technical writer. Sadly, Milly barely knows how to lock her keyboard, has never used a help-authoring tool, and certainly doesn't know how to install beta, undocumented software on a virtual image. The developers then, begrudgingly, write most of the documentation—-which is way over the head of their customers and Milly.

5) And by the way, companies like to save money. They often hire someone who not only cannot install and use beta, undocumented software on a virtual image, but also cannot write complete, lucid sentences. At those times when the technology is way over her head, a good technical writer can identify the nouns, verbs, and objects in the sentence, put them in the correct order, and actually make sense of it; or she can bug the developer until he explains it to her in plain English.

3) Developers are busy and don't want to document how to use their product. "Why, my product is very user friendly and intuitive! We don't need a user guide!" This is where the technical writer's interview and annoyance skills come in handy. A developer will eventually get tired of her questions and actually provide helpful information to a technical writer. (He would just blow Milly off, because she wouldn't understand anyway.)

2) Sometimes (OK, usually), the release cycle is more important that the documentation. The documentation is delivered and signed with help content that is a week or more old. (A lot can change in a week of QA!) In my case, I update the online help and knowledgebase as new issues come to light. (See number 7.) But I’m occasionally left out of the change loop.

1) And finally, the number one reason documentation sucks is that it sits unused. The customer doesn't want to "bother" to read the whole user guide, which could be thousands of topics. Average Joe Customer wants to click Help and have a window appear with a hand that reaches out from the monitor, types the information that he needs to specifically answer his question, and pats him on the back, telling him it will be OK. Dream on Joe. You have to work harder than that.

Here are a few Frequently Asked Questions about Help documentation:

Why did you put THAT in the help? Everyone knows THAT!
Nope, sorry, Mr. Engineer, but not everyone knows how to find the capacitive reactance of a parallel circuit, even if you think it's a prerequisite to using our product. While we'd like to believe that everyone who uses our product is at least as smart as you, the truth is, we aren't.

Why didn't you put THAT in the help?
Because I document *our* product, not Microsoft's, Oracle's, and Java's. Granted, there are some situations that warrant repeating information from their help in our product's help, such as when configuring their product a certain way will make our product not talk to their product. But they have their own technical writers who have worked hard to make their help available to you at publicly available links, so you should use it.

Why can I never find anything in the help?
Let me state this as kindly as possible: you don't know how to search. Before computers, searching talent was reserved for librarians, and we counted on them to find things for us. (Inside every good technical writer is the heart of a librarian.) Now we count on Google to find things for us. Sadly, Google has not penetrated every database in the world—yet—so until they do, we must use our own search skills to find the information we need. And, yes, it can be a challenge at times. If you have honestly searched every possible search word you can think of to find what you want (e.g., script, bat, VB, batch…) and still can't find what you need, send an email to the technical writer of that Help documentation or the product's user forum and say "I searched for "X" in the help using these terms ‘blah, blah, blah’ and couldn't find it." Then I can add those key words to the relevant topics so that next time you will be able to find the right topic. Another point: the application's Help is written for the average user of that product. If you can truly "never find anything" then perhaps you are an advanced user and should instead search the knowledgebase or user forum, or call technical support?

How can I read the help before I install, if installing the product installs the help file?
GOOD question! I've been asking product managers that for years. Well actually what I ask is, why do I need to include installation instructions when no one reads them until after they install, if ever? In my case, the installation Help files are also publicly available online, so you can, if you were so inclined, read the installation instructions online before you install the product. (HINT: Put an "install.txt" file with the installer download!) If you pay extra for technical support, I'm sure the company will hold your hand while you install their product and help you avoid any bumps in the road.

There is so much repetition in this help file, it's ridiculous!
OK, Grandma, calm down. This is called a "help file," and the reader can jump into the story at any part in the story. In fact, it's not a story at all. There is no beginning, middle, or end. It's a collection of "how to" topics, not a novel. So when Mr. Admin is trying to create a user and starts banging his head against his desk because he can't figure it out on his own, he can click "Help," search for "how do I create a user?" and then read a topic called "Creating a User." He doesn't want to know why to create a user. He doesn't want to know what happens at the application level when the user is created. He doesn't want to know where in the database the user is stored. Right now, all he wants to know is, "how do I create the doggone user?"

(And while you're laughing because I formatted a sentence in the help with red, bold text, know that I did that because when it was regular, black text, no one would read it. They would scan right past it. I have yet to make it blink, however.)

A Review of (American English) Grammar, Spelling, Punctuation, and Usage

2009-11-07T14:11:00.003-06:00

Introduction	American vs. British English	What is Grammar?
Common Errors	Spell Checker	Grammar Checker
Usage	Than vs. Then	Who, Which, That
different from vs. different than	Mixed Construction/Parallel Sentences	Sentence Structure
Conjunctions	Pronouns	Adjectives
Articles	Punctuation	Hyphenation
Dangling Modifier	Offensive Phrases	New Words
Compound Words	References	Latin Words and Phrases

Introduction

My degree is in communication, so I'll start with a basic theory of communication.
In simple communication, there are a minimum of four components: sender,
message, medium of transmission, and receiver. A fifth component is often,
unintentionally, introduced: noise.
Rules of grammar, spelling, punctuation, and usage are an attempt to reduce
the noise in communication.

American vs. British English

Why do I say "American English"? Aside from the commonly known differences in terminology (bonnet vs trunk, torch vs. flashlight, lift vs. elevator), American English and British English have several differences in basic grammar and punctuation. For example, in American English, a comma always, always, always goes inside the quotation marks (unless doing so would confuse the reader). Similar rules apply to other punctuation in or out of quotation marks, and the types of quotation marks used (single or double). In British English, you will also hear phrases such as "The team are meeting to decide on the next play." In American English, group nouns such as team are treated as singular. So, the same phrase in American English is, "The team is meeting to decide on the next play." (I hear the narrator on "Mythbusters" often saying, "the team are.." and it drives me batty!!) There are numerous Web sites dedicated to the differences between American and British English, so I won't provide all the gory details here; just be aware that the information below is reflective of American English usage.

Grammar is:

The study of the way the sentences of
a language are constructed
The establishment of rules based on norms
of correct and incorrect language usage
Knowledge or usage of the preferred or
prescribed forms in speaking or writing

Common Errors

Relying too heavily on spell check
Relying at all on grammar check
Not reviewing your work
Writing the way you speak
Believing that since you've "seen
it that way before" it must be correct

Spell Checker

Spell check only checks the spelling of words; it doesn't know if you've chosen the correct word. I suggest leaving the spell check feature turned on, however, so that typos are underlined in red for your attention (in Microsoft Word). (When in doubt, use a dictionary--or hire a tech writer!) Below are several words that are often misused.

your, you're
to, too, two
they're, there, their
advise, advice
affect, effect
adapt, adept, adopt
all right, all-right, alright
all together, altogether
allude, elude
discreet, discrete
eminent, imminent
explicit, implicit
figuratively, literally
good, well
imply, infer
insure, ensure, assure
irregardless, regardless (irregardless
is redundant: "without without regard")
it's, its
lay, lie
lose, loose
and many, many more!

Grammar Checker programs

Here is an example of a sentence that was marked by grammar checker
as having errors:
The managers of the organization meet each morning.

Grammar checker suggested the writer should use meets instead of meet; however, meet applies to managers, not organization, so "managers meet" is correct, not " managers meets." Grammar checker assumes the writer will place modifiers next to the words they modify, which is normally a correct assumption.

Usage

Many words and phrases are misused so often, we sometimes forget which is the correct usage.

Incorrect: Please try and finish the report on time.
Correct: Please try to finish the report on time.

Incorrect: The report simply alluded to the problem, rather than stating it clearly.
Correct: The report simply eluded to the problem, rather than stating it clearly.

Incorrect: The discrepancy in the report eluded the author.
Correct: The discrepancy in the report alluded the author.

Incorrect: The wind tunnel did not effect her hair style.
Correct: The wind tunnel did not affect her hair style.affect is a verb

Incorrect: What affect did it have?
Correct: What effect did it have?/What was the effect?

Incorrect: He was already to start work on the project.
Correct: He was all ready to start work on the project.
Better: He was ready to start work on the project.

different from vs. different than

In formal writing, the preposition from is used with different.

The fourth-generation computer is different from the third-generation computer.
Different than is acceptable when it is followed by a clause.

Than vs. Then

Than is used for comparison: One is smaller than two.
Then is used for time: First I'll go home, then I'll put my feet.

Whom vs. Who

If you can use him/them, you should use whom:

Do you need to call him?
Whom do you need to call?
You need to call them?
You need to call whom?
"Who ya gonna call? Ghostbusters!" s/b "Whom ya gonna call?" But in this case, its obviously informal communication.

Who, Which, That

Who refers to persons.
That and which refer to animals and things.
That, rather than which, should be used with restrictive clauses.

Hint: If you can surround it with commas, use which.

Compare:

After John left his house, which is on the corner, he went straight to work. (nonrestrictive)
A company that diversifies often succeeds. (restrictive)

Latin Words and Phrases

ad hoc (for this) no hyphen:
The ad hoc committee will meet this Thursday.

per diem (per day) no hyphen:
The field service reps will be paid $30 per diem.

i.e. (id est, that is):
The big dog (i.e. the Golden Retriever) is sick.

e.g. (exempli gratia; for example, such as):
Big dogs (e.g. Golden Retrievers and Great Danes) make great family pets.

sic (thus) verbatim:
"I aint gonna (sic) do it!"

Mixed Construction/Parallel Sentences

Mixed construction occurs when a sentence contains grammatical forms that are inconsistent with one another.

I will check your report, and then it will be returned to you. (active to passive voice)

To make it parallel, change it to:

I will check your report, and then I will return it to you.

The bulleted list that follows is not parallel:

The following recommendations were made regarding the position statement:

Stress that this statement is for all departments
Start the statement with "If the company"
The statement should emphasize that it applies both to department managers and staff
Such strong words as obligation, owe, and must should be replaced with words that are less harsh

To make it parallel, make each bullet an imperative (do this, do
that):

The following recommendations were made regarding the position statement:

Stress that this statement is for all departments
Start the statement with "If the company"
Emphasize that it applies both to department managers and staff
Replace such strong words as obligation, owe, and must with words that are less harsh.

Hint: In a list, use bullets for steps that do not have to be completed
in any particular order. Use numbers ONLY if the steps must be completed
in that order:

Open the microwave door.

Insert food.

Close the door.

Select cook time.

Press Start.

Where possible, only put one step per bullet. If there is only one item, it should not be in a bullet. Either make it into a sentence or note, or add more bullets.

Sentence Structure

Identify the parts of speech in the following sentence:
John often throws beach balls with his feet.

Subject	Adverb	Verb	Adjective	Direct Object	Prepositional Phrase
John		throws		balls
John	often	throws	beach	balls	with his feet

(Compare: The beach balls were thrown by John. Balls is now an indirect object.)

Conjunctions

A coordinating conjunction is used to join parts of a sentence or to separate clauses that are equal in rank. Using coordinating conjunctions makes the reading more smooth, less choppy. For example: He was angry. He got over it. He was angry but he got over it.	and or but for nor yet so
Correlative conjunctions are coordinating conjunctions that are used in pairs. Correlative conjunctions need parallel sentence elements. For example: He was not only handsome, but also very intelligent.	either, or neither, nor not only, but also both, and whether, or
Subordinating conjunctions connect sentence elements of varying importance. Although no one will actually follow her advice, she spent hours putting together the grammar presentation. The phrase "Although no one will actually follow her advice" is subordinate to the phrase "she spent hours putting together the grammar presentation."	Most common are: so although after because if where than since unless as before though when whereas

Dangling Modifier

Phrases that do not clearly and logically refer to the proper noun or
pronoun are called dangling modifiers. They are usually caused by overuse
of the passive voice.

While eating in the cafeteria, the computer
malfunctioned. (Was the computer eating in the cafeteria?)

While the operator was eating in the
cafeteria, the computer malfunctioned.

The man rented a house with his son,
which cost $400 per month. (Did the son cost $400/month?)

The man and his son rented a house for
$400 per month.

Pronouns

Personal pronouns refer to the person(s) speaking or being spoken to or about. I am very tired right now.	them they his he your you mine me I
Demonstrative pronouns must have an antecedent. I keep finding typos in this presentation. (Presentation is the antecedent, i.e. the word to which "this" refers.)	this that these those
Relative pronouns link a dependent clause to a main clause. I am the technical writer who created this presentation.	who whom which what that
Interrogative pronouns ask questions. Who am I?	who whom wha twhich
Indefinite pronouns specify a group of person or things rather than a particular person or thing. All good things must come to an end.	all any another each both
Reflexive pronouns indicate that the subject of the sentence acts upon (reflects) itself. (See examples below this table.)	myself yourself himself herself oneself themselves ourselves
Intensive pronouns act like reflexive pronouns but give emphasis to their antecedents. I myself asked the question.
Reciprocal pronouns indicate the relationship of one item to another. People should always respect one another.	one another each other

Compare the following sentences that use personal pronouns:

Incorrect

Correct

Me and him went to the store.

	Me went to the store.
	Him went to the store.

He and I went to the store.

	I went to the store.
	He went to the store.

He went to the store with she and I.

	He went to the store with she.
	He went to the store with I.

He went to the store with her and me.

	He went to the store with her.
	He went to the store with me.

Please call my assistant or myself to make an appointment.

Please call myself to make an appointment.

Please call me or my assistant to make an appointment.

Please call me to make an appointment.

Personal pronouns and gender-specific wording

There is no singular personal pronoun in English that refers to both
sexes. He is traditionally used when the sex of the antecedent
(the noun that he refers to) is unknown. The use of a masculine
pronoun (he/his) to refer to both sexes can be offensive. It is better
to rewrite the sentence in the plural or avoid use of a pronoun altogether.
(Many American and English writers [Shakespeare, Shelley, Dickens] have
used they and its forms to refer to singular antecedents, but it's considered
a "no-no" by many editors.)

The engineer cannot do his job
until he understands the concept.

Engineers cannot do their jobs until they understand the concept.

The technician should take care in choosing his equipment.

The technician should take care in choosing
equipment.

If we hire another nurse, she could help us complete the task.

Hiring another nurse would help us complete
the task.

While we're on the subject of offensive
phrases...

Based on a survey of 7,500 managers and executives enrolled in writing
programs, the following phrases were deemed offensive:

"To be perfectly honest" suggests
that everything else has been dishonest.
"Needless to say" contradicts
whatever follows, so skip it.
"Enclosed herewith, please find"
is wordy and dated; substitute "enclosed is" or "enclosed
are"
"As you know," "as you
are aware," "as per our conversation" are unnecessary and
may sound insulting; omit them.
"I am writing this letter to inform
you" states what is obvious to the reader.
"Please rest assured" sounds
"as if you're asking the reader to take a nap," said survey
respondents.
"Please be advised that" wastes
time and says nothing.
"At your earliest convenience"
and "as soon as possible" are too vague; provide a specific
date.
"If you should have any further
questions, please do not hesitate to contact me" is overused. Find
a fresher expression, such as "Please call if you have any questions."
"For your perusal," "review,"
"consideration" are outdated and pretentious. All of these phrases
should be avoided by contemporary business writers.

Adjectives

Anything that modifies a noun functions as an adjective.

Articles

Indefinite	Definite	Demonstrative	Possessive	Numeral
a an all none some any	the	this that these those	my his her your our their	two first
A dog was barking.	The dog was barking.	That dog was barking.	My dog was barking.	Two dogs were barking.

Punctuation

Just as body language cues us in to what another person is saying, so
does punctuation clarify what is written.

Commas are used to:

Introduce a word or phrase:

He needed only one thing, encouragement.

(Or: He needed only one thing: encouragement.)

Separate independent clauses:

He did not like his work, and his distaste
for it was evident to everyone.

(Comma optional here. Since they are two independent clauses, they could
also be two separate sentences.)

Enclose parenthetical words, phrases,
clauses:

Note, for example, the illegally parked
bus.

Indicate omission:

He takes his work seriously, himself
lightly. (He takes is omitted in the second half.)

Make a series more clear:

	I request that all of my worldly goods be split equally between Jim, Jacob, Sarah, and Susie. (Each gets 25%, right? Well, maybe 20% each--the lawyer gets his share, too!)
	I request that all of my worldly goods be split equally between Jim, Jacob, Sarah and Susie. (Do Jim and Jacob each get a third, with Sarah and Susie sharing the other third? The law says, yes.)

Ellipses

Ellipsis dots are not used to introduce a series or a bulleted list.
Do not use ellipsis dots for any purpose other than to indicate omission,
such as when quoting a source from which you have edited words. Be careful
when you do omit words to not change the overall meaning.

The letter states "the programmer
and the developer must create a system flowchart."

The letter states "the programmer ...
must create a system flowchart."

Quotation Marks

Both double (") and single (') quotation marks
are for enclosing words, phrases, clauses, sentences, paragraphs, and
groups of paragraphs.
Quotation marks are used for:

Direct quotations

Lengthy direct quotations

Change of speaker

Titles and names (Underlining or italics
s/b used in word processing)

Quotation w/in a quotation

Place marks correctly with reference to other marks. (British usage
is exactly reversed from American usage.)

The comma and the period always come inside the quotation marks.

	"Well," he replied, "Im not sure." Then he inquired, "What do you think is fair ?"
	He referred to it as a "gentlemans agreement," but to me it was sheer " bunk."

A question mark, exclamation point, or
dash come outside the quotation marks unless it is part of the quotation, as in the first example:

	"What will my starting salary be?" asked the manager.
	Did he say, "I have enough money"?
	The performance was a "flop"!

The semicolon and colon come outside
the quotation marks:

Study the following in "Human Anatomy":
Bones

Colon

A colon is used for:

Introduction

My goal in this job is simple: success.

Separation (as in subtitles)

Education
for College: Improving the High School Curriculum

General rules of usage:

Never use a colon directly after any
verb, or the conjunction that.

Do not place a colon between a preposition and its object

Hyphenation

Hyphens may be used to avoid ambiguity
and difficult reading, but if misreading is unlikely, the compound may
be closed.

re-create (vs. recreate)

biomedical

multifaceted

interrelated

anti-inflammatory (double vowel)

co-opt

Compound adjectives should be hyphenated,
as in

labor-intensive report

two-digit date fields

on-staff engineers

Y2K-Compliance Assessment (vs. Y2K Compliance)

New Words

Many words in common use today are relatively new, or are old words
being used in a new way. Therefore, the "rules" for their use
are not firmly established. Some examples are:

Internet (capitalized)
intranet (not capitalized)
online
email, e-mail, or E-mail (AKA "evidence
mail" Keep that in mind when you send them!)
Web page (capitalized)
Website (capitalized)
browser, site, server
protocols
logon, log on

The Logon dialog box appears. (noun)
Log on to the network. (verb)

Compound Words

An open compound is a combination of separate
words that are so closely related as to constitute a single concept, such
as stool pigeon.
A hyphenated compound is a combination of
words joined by one or more hyphens, such as mass-produced goods.
A closed or solid compound is a
combination of two or more originally separate words that are now spelled
as one word, such as notebook.

For some years now, the trend in spelling compound words has been away
from the use of hyphens (except for words like e-mail, which refuses to
die). This is a trend, not a rule. After they are in common use for an
undefined amount of time (usually, after they make it into a dictionary),
they go from being temporary compounds to permanent compounds.
When a compound is used as an adjective before a noun, it is often hyphenated
to avoid misleading the reader.
For example, Bob's first-floor apartment is hyphenated to make it clear that you mean an apartment on the first floor, rather than it was Bob's first apartment.
The phrase, sixty-five-year-old men is hyphenated to make it clear that the men are 65 years old,
rather than there being 60 five-year-old men.
However, the phrase much loved friend is understood as is and requires no hyphen for clarification. Note also that foreign words and phrases are usually not hyphenated, as in ad hoc reports. There are pages and pages of rules and exceptions having to do with hyphenated compounds. For example, half-baked plan is hyphenated (as are most half compounds) but halfway house and halfhearted attempt are not. (These are examples of temporary compounds that have become permanent compounds through widely accepted use. BTW, words ending in ly are not hyphenated since ambiguity is unlikely.) When there are multiple adjectives in a compound, each is hyphenated, as in Do you manage other customer- or business-sensitive data, to indicate, in this case, that the data is both customer sensitive and business sensitive. Without the hyphen, the sentence is asking two separate questions: Do you manage other customer? (which makes no sense) and Do you manage business-sensitive data?

References

Most of the examples and "rules" in this presentation were
taken from:

Handbook
of Technical Writing by St. Martins Press

Punctuate
it Right! by Harry Shaw

The
Computer Encyclopedia by Alan Freedman

The
Chicago Manual of Style by the University of Chicago Press

"Don't Use These Phrases!" Winning Strategies for Corporate Communication, Springfield, Virginia:
Communication Concepts, 1991.

Stupid Things RoboHelp Does

2009-11-07T13:32:00.006-06:00

Stupid Things RoboHelp Does

Update: I recently updated to RoboHelp version 8. So much improved over version 7! The Search improvements alone are worth the upgrade!
---------------------
The meat and potatoes of a "real" technical writer's job is making context-sensitive help files that are embedded in software applications, often in addition to Web-based help and printable user guides. There are numerous "single-source" applications that you can use to, in theory, compose once and generate the several types of help you need (PDF, CHM, Web-based, JavaHelp, Oracle Help, etc.). I've used a variety of these so-called single-source authoring tools, and none of them is truly single-source. If you don't have to meet any specific requirements, then RoboHelp, Flare, Doc-To-Help, AuthorIT, Notepad, and such will likely provide what you need. But if your output must meet specific requirements, that single-source authoring tool will need your creative and research skills to figure out how to "fix" the output.

For a help authoring tool, RoboHelp has notoriously bad help. Meaning, when you click Help in RoboHelp, I very rarely find the help I need. If you search the Internet for help, you will find numerous experienced RoboHelp users with awesome Web sites to provide some of the more common tips, as well as tips for very advanced users (e.g., Peter Grainge's Site, RoboWizard, Google Groups).
Below are a few tricks I've discovered while using RoboHelp. Come back here from time to time as I find other stumbling blocks. Unfortunately, by the time I figure out how to fix the problem, I'm usually in a hurry to get past it and don't think to document what I did. But it always manages to find me again. There are many, many, many more that I've never documented, but when I stumble across them again, I'll add them here. :-/

Perhaps you have a better solution? If so, please let me know in the comments.
Below are real problems/needs that I encountered and the solutions that worked best for my situation. I encourage you to experiment with the code (after judicious backing up and copying) to find the solution that works for you.

Problem/Need: I had been fighting doing merged chms because it's more complicated for print and I like having the WebHelp all in one project. But as the project got bigger, it became clear that it would be much easier to manage the project in pieces with merged helpsets, so I bit the bullet a while back and did it. Today I wanted to link topics between merged helpsets and FINALLY found a clue. The info I found online finally worked after I played with the link (based on what I knew from linked JavaHelp).
Solution: Without any help from RoboHelp's help, I found that when you insert the hyperlink, in the Hyperlink dialog box, you can click the Link to arrow, then click Remote Topic. Then the Select Remote Topic dialog box opens, in which you can select the merged helpset's chm (which you've already copied to the Source folder), then click the topic filename. The link is similar to a normal "a href" link, but with the filename of the chm, 2 colons, and a forward slash in front of the htm. The code looks like this:
<a HREF="gs_com_api.chm::/Setting_the_expiration_date_for_a_user_account.htm">Setting
the Expiration Date for a User Account (SetExpirationDate)</a>

In this example, the text the user sees look like this:
Setting the Expiration Date for a User Account (SetExpirationDate)
When I clicked the eyeglasses icon (preview) it didn't work, but when I compiled, it actually worked.

Problem/Need: WebHelp does not appear correctly in Google Chrome (the TOC, Glossary, Index, Search tabs are blank)
Solution: Adobe posted a fix on their support pages (within ONE DAY of complaining!): Chrome fix

Problem/Need: A topic named "Using the Software with IIS" was not coming up in a search for "IIS." I suspected the stop words were preventing it from appearing, so I deleted "is" from the stop words. Nope, didn't fix it. Then I found RoboHelp's stop words file and edited that. Nope, didn't fix it. Then I edited the stop words file from the generated help. That fixed it. But when I regenerate, it will over write it.
Solution: I really hate it when apps try to think for me! I removed the stop words from the project FOR A REASON, and when I generated, the stop words reappeared in the project. So when I edited RoboHelp's stop words file, the stop words had already been added back to the project. I saved my "clean" stop words file away from the generation folder, but it would be nice if RoboHelp just let me do the thinking. :-?

Why Do You Need a Technical Writer?

2009-11-07T13:17:00.011-06:00

Why do I need to hire a technical writer?

My intern did a fine job on that manual last year.

Sure there were a few spelling and grammar errors,

but Word caught most of them.

We don't have time to create online help,

but, hey, no one reads it anyway!

That's why we have a help desk!

Having an on-staff technical writer, whose only job is to create properly written, prepared, and presented documents, shows customers that you endeavor to provide a quality product and encourages repeat business.

As technology inserts itself into every aspect of daily life, there is an increasing need for clear, concise, accurate documents to explain that technology. To minimize training and customer-support overhead, savvy business managers provide professionally produced user guides and tutorials. If developers, engineers, or other high-level staff are writing your user guides, not only are you getting a sub par, hastily prepared document, but you are taking time away from your staff's development, engineering, or other important tasks. Providing incomplete, inaccurate, confusing documents puts a negative face on your organization and encourages potential customers to take their business elsewhere.

Unfortunately, many companies provide user guides simply as an afterthought or to fulfill a customer requirement.

"Manuals" are frequently written by engineers who don't want to "waste" their time writing help files--often with English as their second language. Many companies will ask managers or assistants to produce end-user documentation, resulting in documents that are hardly worth the paper they are printed on--or the salaries expended in their production.

A skilled technical writer researches the document's target audience, determines the information required, and delivers it in a format that fits the need.

Engineers or developers might be experts in their fields, but advanced writing skills are not normally a part of their college curriculum. Technical people typically write to impress other technical people, rather than to get their point across in the most clear, concise manner possible. Also, a salesman's or manager's silver tongue in the boardroom doesn't necessarily translate well into writing. On paper they can seem pompous and lacking in necessary information.

Technical writers design, write, edit, and manage a variety of documents.

"How-to" guides
Training guides
Policies and procedures guides
Newsletters
Reference books
Company newsletters
Annual reports
Business reports

Software user guides
Hardware user guides
Installation guides
Online help
Online tutorials
Computer-Based Training (CBT)
Operating instructions
Web site content

Promotional mailings
Brochures
Slide presentations
Standardized forms
Articles for newspapers, magazines, journals
Questionnaires/surveys
Templates
White Papers

Expertly prepared and managed documents improve every aspect of your business:

Current customers become repeat customers when accurate and easy-to-use guides are provided with your product.
Well-written and informative catalogs, corporate reports, and marketing materials attract clients and investors.
Clear, comprehensive training and procedures documents make employees more efficient.
Accurate and clearly written policy manuals avoid legal hassles with employees.
A well-written and organized Website presents a professional image to potential customers.

How do you stay on an elliptical machine for more than 30 minutes?

2009-02-17T23:24:00.004-06:00

Because my cholesterol count seems to have a direct relationship with my weight, and because I am, embarrassingly enough, SIXTY pounds heavier than I ought to be, I’ve started exercising again.

I had a treadmill that I used sporadically for the past 7 years (?), and it was very easy to jump on for ½ an hour while I watched TV or listened to the iPod. Then Bill messed up his knee and decided that he needed a more low-impact machine. He bought a Precor elliptical—and moved my treadmill out of the living room. (He claims I never used it anyway. BAH!)

I really tried to love the elliptical as much as my treadmill, but at first I could barely do 5 minutes before I was ready to pass out! Eventually, I figured out to change the settings (he had it on max resistance and max incline!) so that I can now last a bit longer, depending on my mood. And my mood is greatly improved if I listen to dance music while I exercise.

I downloaded some songs in iTunes and made a new playlist. I managed to get on the elliptical every day this week, so far (Sun-Tues). The first 20 minutes about kill me, and then I have a semi-slow song to catch my breath. I found it's easier if I close my eyes (with both hands hanging on!) and pretend I'm dancing. I went for 30 minutes today, which, for me, is great. Below are the songs I listen to while I exercise, which I chose for the tempo/beat, and for the words.

Lose Yourself, Eminem: (Slow start, to get warmed up) “You better lose yourself in the music, the moment, You own it, you better never let it go, You only get one shot, do not miss your chance to blow, This opportunity comes once in a lifetime” (You only get one life, apparently.)
Sexy Back, Justin Timberlake: (It has slow and fast parts to get the burn going) “Get your sexy on, go ahead be gone with it.”
Jerk it Out, Ceasars: (fast beat) “Wind me up Put me down Start me off and watch me go I'll be running circles around you sooner than you know”
Work That, Mary J Blige: (good steady beat--I'm warmed up now) “There's so many of you girls, I hear you been runnin' from the beautiful queen that you could be coming...I just wanna be myself, don't sweat girl, be yourself. ...Work your thing out...work what you got.” (Sorry, Mary, but I'm sweatin' now!)
Womanizer, Circus, Brittany Spears
Disturbia, Rhianna (slightly faster beat--can't sing along as easily) “What's wrong with me now? Why do I feel like this? I'm going crazy now.”
Don't Stop the Music: Rhianna: (I have to close my eyes and imagine I'm dancing. I might pass out if I look at my heart rate.) “Please don't stop the music, I gotta get my body movin' shake the stress away, and now we're rockin' on the dance floor acting naughty”
Harder to Breathe, Maroon 5: (Time to slow it down--it really is harder to breathe) "You drain me dry and make me wonder why I'm even here..is there anyone out there, 'cause it's getting harder and harder to breathe"
Apologize, Timbaland: (Slower, time to cool down)

Many others that I never stay on long enough to get to unless I skip songs!!

Writer I Am

What's Happening to "affected"?

Creating an Hourly Reminder in Windows

Surviving College Past the Second Year

Why does documentation "suck"?

A Review of (American English) Grammar, Spelling, Punctuation, and Usage

Introduction

American vs. British English

Grammar is:

Grammar Checker programs

Usage

different from vs. different than

Than vs. Then

Whom vs. Who

Who, Which, That

Latin Words and Phrases

Mixed Construction/Parallel Sentences

The bulleted list that follows is not parallel:

To make it parallel, make each bullet an imperative (do this, do that):

Sentence Structure

Conjunctions

Dangling Modifier

Pronouns

Compare the following sentences that use personal pronouns:

Personal pronouns and gender-specific wording

While we're on the subject of offensive phrases...

Adjectives

Articles

Punctuation

Commas are used to:

Ellipses

Quotation Marks

Colon

Hyphenation

New Words

Compound Words

References

Stupid Things RoboHelp Does

Stupid Things RoboHelp Does

Why Do You Need a Technical Writer?

Having an on-staff technical writer, whose only job is to create properly written, prepared, and presented documents, shows customers that you endeavor to provide a quality product and encourages repeat business.

Unfortunately, many companies provide user guides simply as an afterthought or to fulfill a customer requirement.

A skilled technical writer researches the document's target audience, determines the information required, and delivers it in a format that fits the need.

Technical writers design, write, edit, and manage a variety of documents.

Expertly prepared and managed documents improve every aspect of your business:

How do you stay on an elliptical machine for more than 30 minutes?

To make it parallel, make each bullet an imperative (do this, do
that):

While we're on the subject of offensive
phrases...