Formal writing vs. informal writing

I get paid to write technical documentation, not dime novels, not romance novels, not teen books. In technical writing, you have to be clear and concise, use words that your audience will understand, use active voice, write in the second person (do this; now do that), and use proper grammar and syntax. When writing novels, you get to make the rules—it’s your novel! If you want to break the rules, break the rules! The only rules are the rules that you make. You can call that your “style” if you want. But you still have to be consistent, and still have to consider your audience. You don’t write in French if your audience speaks only English.

  • Writing technical documentation and business documentation is considered formal writing.
  • Writing a novel, this blog, emails to friends, Facebook posts, tweets, and so on is informal writing.

“Well duh,” you’re saying. “Like I didn’t know that already.” Well, no, it doesn’t seem so, because I’m frequently called out for not following the rules of formal writing when I write informally. If you’re writing a Facebook post using “gangsta slang,” I don’t feel the need to correct you. 1) it’s not my job and 2) it’s your style. The same goes for my writing on social networks–I’m writing for me, not for my employer.

Like most people, I write the way I speak, unless I’m writing for someone else. When I’m writing for the company that I work for, it’s important that it be written correctly for the audience, which in my case is the computer/IT crowd. That’s not to say that a non-computer/IT audience wouldn’t understand the writing. It’s also important, as I said earlier, to be clear and concise.

The “average” American adult reads at the 7th or 8th-grade level. That’s pretty sad, but remember that it is an average. Some people don’t read as well, and others read at a higher level. If you’re writing for your English Literature professor, obviously you’re going to use less common/more pompous language than the average American uses/sees every day (e.g., “lacrymose” instead of “weepy’). So writing at the 8th-grade level should be OK for most of your audience. Also keep in mind that, even though I’m writing toward a computer-literate audience, the particular technology that I’m writing about might be new to some of our customers, especially since computer technology changes quite frequently. It’s also quite possible that the IT person you have in mind for your user guide might not have graduated from high school (e.g., got a GED and then went to a technical school or had military training), or maybe English was not his first language. Some things get lost in translation. That’s also why it’s important to pay attention to grammar and sentence structure—easier to translate.

The Plain Language “movement” (for lack of a better word) has been going on since the 90s. I really don’t know why it hasn’t caught on. The idea is very much “techwriter 101″—use clear, plain language that anyone could understand or translate easily. (They do say, however, don’t write for an 8th grade audience if you’re sure your audience is made up of PhD candidates.) President Obama signed the Plain Writing Act of 2010 on October 13, 2010, but it’s bigger in the UK than in the US. Medical, legal, and other professionals are encouraged to write in plain language so that their constituents know what the heck it is they’re reading. What a concept! I guess we just feel more important when we use “big” words.

Whatever style you’re more comfortable writing in, write that way! And read what you like to read, not what someone else told you that you “should” read. If you want to write in a certain style, read more books in that style. That is, if you want to write user guides, read user guides, technical manuals, and so on. If you want to write like Dave Barry, read Dave Barry. If you want to write like Charlotte Brontë, read Jane Eyre. But don’t read Charlotte Brontë and then try to write user guides that way. You will definitely lose your audience. However, injecting a little Dave Barry into user guides might encourage more people to read them!


Word Tip: Inserted Picture in Word is Cut Off by Preceding and Following Paragraphs

A coworker asked for my help with this issue. He was working in a document that he had received from someone else. He placed the cursor in front of a paragraph, pressed ENTER, then inserted a picture. He could see the outline of the picture when the picture was selected, but only a small piece of the picture appeared in the line where he had placed it:


He checked the picture layout (i.e., Text Wrapping > Behind Text), and everything was fine. Then he asked for my help.

I selected the paragraph into which the picture was inserted. Then I opened the Paragraph dialog box to check the line spacing:


The Line spacing was set to “Exactly 12 pt” which means no matter what he did to the picture, it was only going to show exactly 12 points of it. Changing the Line Spacing to “Single” allowed the entire picture to appear:


Why did this even happen? For some reason, that document’s “Normal” style had line spacing set at exactly 12 points. There really is no reason for this in “regular” documentation. If you were doing something fancy with layout, you might want to adjust the line spacing. But plain old “single” spacing is usually fine for most documents, and that line spacing will adjust automatically depending on the font size. (The same reason that you do NOT have to double space after a period!)

In addition, what’s more, I disagree with that also, too

I often hear speakers say “also, too” in a sentence. Using both words in a sentence is redundant. They are synonyms.

Below are the definitions of “also” and “too,” according to Google:



Notice that “too” is listed under synonyms for “also,” and “also” is listed under synonyms for “too.”

Other synonyms that often appear in this type of error are “as well as,” “additionally,” “furthermore,” and “in addition.”

For example, this is something you might see in a company press release:

“In addition, he is also the CEO, as well as the president.” “In addition,” “also,” and “as well as” all mean the same thing. It’s redundant. It would be like writing, “Also, he is also the CEO, and also the president.”

You could rewrite that to something like, “Mr. X is both the CEO and the president.”

Why We Need Standards

No matter what you’re doing, you need to follow a standard. “But, Karla,” you say, “That’s just being anal. Everyone has their own way doing things.” Yes, everyone does. And that’s a problem.

Standards can be applied when cooking dinner, documenting a software product, coding a software application, performing a pre-flight checklist, or operating on someone’s brain. If everyone is “doing their own thing,” accidents happen, steps are skipped, errors are made, and the next person has to spend lot$ of time and energy to figure out what the heck you did. If you’re following a standard, everyone is on the same page.

“Should I manually format this document or should I use a style sheet? Meh, what do I care? I’ll never touch this document again.” Let’s suppose the document is content for a company newsletter. The company name has changed, the design has changed, everything that was orange is now supposed to be red, and so on. The person who has to update your lazily formatted document has to manually change all of your manual formatting, or create a style sheet and apply the style sheet throughout the document. Neither process is fast, and both processes are tedious—this time. But if you use a style sheet, the next time the document has to be updated, e.g., if the color scheme needs to be changed again, you only have to update the style sheet, not the whole document.Preview Changes

“Should I number every step or use bullets?” For this one, you don’t need to guess. Every technical writer who knows what’s she’s doing knows that you number steps that are to be performed in order and use bullets if order does not matter. That’s the standard for technical procedures. It’s not confusing. Yet so many “writers” do this wrong.

Do I write “Either of these dogs is the father” or “Either of these dogs are the father”? Either IS! That’s a grammatical standard.

On the GUI, how do I order buttons? Is it OK, Cancel, Help, or OK, Help, Cancel, or…? That depends on whether your group follows Windows guidelines, Apple guidelines, or Java guidelines. Find out which standard you’re following, if you’re even following one, so that you all follow the same guidelines. Hours of engineering time ($$$) are wasted “fixing” the previous programmer’s non-standard code, and the workarounds constructed because of the code. There are more complex coding standards that I have no clue about. The point is: Follow. The. Standard.

“What standard?” That depends on what you’re doing and who’s in charge. Ask your manager what the standard is. If he’s confused, discuss standards with your coworkers. If you can come to an agreement over which standard you should follow, then you’re halfway there. Getting people to stick to the standard is much harder.

When you get into an airplane, you hope that the pilot has followed the preflight check list. When you have surgery, you hope that your surgery team has followed commonly accepted protocols. And when you open up a document that you didn’t write and it’s your job to update it, you really hope that the author has followed a standard.

What’s the grammar rule for this?

I’ve been asked questions like this numerous times. The person asking wants a black or white ruling, but the “correct” usage is often very gray. And very often, there is no “rule” but rather a choice to make, either on the part of the author or the editor.

The Chicago Manual of Style has a Q&A section each month in its online version of the guide. This is from the April 2013 Q&A section:

Q. Where in the manual will I find guidance to answer the question whether the adverb structurally in the phrase “structurally modify or upgrade” qualifies only the verb modify or both the verbs modify and upgrade? I have looked at paragraphs 5.143 through 5.161 (15th ed.) but don’t perceive the guidance I need.

A. Alas—the great and powerful manual cannot tell you what this writer was thinking. The only way to know for sure is to ask him or her. If you don’t have access to the writer, then you will have to settle for ambiguity. If you need to know the exact meaning because you’re involved in a lawsuit whose outcome depends on the technical meaning of this phrase, you’re at the mercy of the judge. If you are the judge, well, good luck.

So how do I decide what is the “right” answer? If I am not the author, I ask the author for more information. If I am the author or the editor, I try to write the sentence a different way to see if that changes the meaning or intention of the sentence. I review my source material to be sure I understand what it is I’m supposed to be writing about.

When I was studying French in college, the professor would ask us to answer a question about usage, and then ask why we think our answer was correct. The point was to help us learn how to apply the variety of rules one needs to know to speak (or write) French without sounding like a 2-year-old French child. I don’t recall the exact question now (having to do with liasion), but I gave my answer and then the professor asked, “Why?” I replied that “it just sounds right.” I heard mumblings from fellow students about how stupid my answer was, but the professor said, “Yes! You got it! It sounds right to you, because you’ve absorbed the rule and can apply it instinctively!” (Then he proceeded to ask the mumblers to cite the rule.)

Every day, we apply “rules” of grammar, sentence structure, and style based on our experiences. If we had to “look up” everything, we’d never speak, let alone get any writing published. Those of us who have studied grammar, sentence structure, style, etc. write and edit based on years of writing and editing a variety of works, making mistakes, learning from those mistakes, and remembering the corrections. I can’t cite every rule (I wasn’t an English major), but I know enough about it that if you need a ruling, I can Google the answer for you. (Or better yet, Google it yourself. You’ll remember it better that way!)

We don’t always have a written rule to follow. Styles don’t follow rules (other than the rules set by the person who wrote the style guide.) Do you think e. e. cummings followed rules and styles? Of course he did! But it was a style of his own making, which is not wrong (in poetry) when you apply the style consistently. Usually, we follow the rules for the type of writing that we are writing or editing. That is, the rules for writing technical user guides are not the same as the rules for writing poems or advertising copy (“Got milk?”).

And sometimes we have to go with our gut—or with whatever looks or sounds right.

End-User Collaboration and Feedback

For the products that I document, the help documentation is installed and/or available as WebHelp for every product and every customer. They don’t have to go online to find it; they just click in the product to open the Help. This makes the help topic the perfect place for a feedback form—on the same page where they were looking for or found the help they needed to use the product to its full potential. Why do I want a feedback form on every help topic? Enabling collaboration in Help allows users to contribute and share information. Their feedback would allow me to refine and improve the Help and product usability, and assist with sales/marketing efforts. Users’ shared comments improve the Help experience, and gives the user a sense of “ownership” of the Help content (which means they’ll use it more).

Getting Management Buy-In for Feedback

Managers are often loathe to spend money for a technical writer, let alone for user feedback. Explain to your manager the many benefits to user feedback. Not only can it improve the help itself, but also can serve as a marketing tool. (i.e., who is using our product help, and therefore, who is using our product?) Comments can be used in marketing materials (minus any identifiers like full name or company name).

This is from

Business Benefits and Risks of UGC for Technical Documentation

User-generated content can help businesses reap additional benefits. Reader commentary can be instrumental in identifying the concerns of users. Based on user feedback, we can modify content to suit the needs of our audience. Creating more effective technical documentation also reduces the cost of helpdesk support. At the same time, UGC can serve as a strong marketing tool. A product’s audience can best reflect its proper market position. Good testimonials that a product’s customers or users have provided can work wonders in increasing its user base—delivering on the promise of greater adoption.

Feedback Management

Certain websites exist for the sole purpose of feedback form management and tracking, with varying levels of complexity.

Adobe Forms Central allows you to design your own feedback form, and the responses are stored on their website. However, it’s not free if you want more than one form or more than 50 responses. Their “Plus” plan is $143.88 per year, which allows unlimited forms, with a max of 5,000 responses per form. You can view the form that I made (from their templates) here. Adobe provides a link to the survey that you can email, embed in a webpage, or even send via Twitter. In the administration pages, one page shows the comment and the respondent’s email address in a spreadsheet format. You can also export the responses to Excel. A Summary Report has charts and graphs of data gathered.

Survey Monkey is widely used and has free and paid levels starting at $204 per year. As with Adobe Forms, it involves linking to an external website.

I think Survey Monkey and Adobe Forms are more than what I need regarding Help usage, plus the jumping out to an external website with no tracking of which topic they were on when they decided to submit a comment is a problem.

MadCap Feedback integrates with MadCap Flare (competitor to RoboHelp) and works with their Feedback Server or MadCap Hosted Service. In addition to comments, it allows you see which search keywords were entered by users. From their user guide:

“Let’s say that many users are entering the search term “sofa.” Unfortunately, you have not used that word in your project, so users are unable to find the topics that they need. However, you have used a similar word, “couch.” Therefore, in the Synonyms Editor, you enter “couch” as a synonym for “sofa.” The next time a reader enters “sofa” as a search keyword, topics containing the word “couch” will be returned in the results.”

Of course, I can do something like this in RoboHelp, too—IF I know which words they are using and not finding what they need. MadCap Feedback can work with any WebHelp (not just Flare projects). This app would provide a more detailed view of how our customers use our software and the Help files. The advantage to MadCap Feedback is that it was developed for exactly this purpose. They have group and one-on-one training ($$) for installation and setup. But Feedback is not cheap: $2,499. (Their Hosted Service is a monthly charge.) I imagine this would be something to try after trying a free or low-cost method to determine if I really want to do this.

Self-created and self-managed form

The alternative to online forms/survey managers is to create my own form, manage the inflow of emails, generate reports, and create/manage the database myself. If we have a tool that we’re currently using that could be expanded for this purpose (and includes reporting) that would be even better.

The design of the form would depend on the information that we want to gather, such as:

  • Was the information easy to find?
  • Was the information clearly represented?
  • Did this information solve your problem?
  • What can we do to improve this information?
  • What were you searching for?
  • What search words did you use?
  • Overall, how would you rate this Help documentation?

Of course, that’s too many questions. At the very minimum, I want to a display a comment box and ask them to leave a comment. When they click Submit, it would send an email to a dedicated mailbox, not to my mailbox. I would add something like this, at the bottom of every help topic:

Feedback Form

I already have the text above at the bottom of every help topic, plus “Leave compliments or complaints regarding the help in the User Forum.” But I’ve never found anything in the User Forum specifically for the Help. I think allowing users to comment directly in the topic, versus linking to yet another web page, would encourage more users to provide feedback.

Do you ask for user feedback? If so, how do you do it? If not, why not?

There, Their, They’re, It’s OK!

Even experienced writers occasionally write the homophones (words that sound the same but have different meanings) there, their, they’re, and even there’re incorrectly. They don’t usually make the mistake on purpose; they just aren’t paying attention. When I’m writing an email or text, I don’t give it the same care and attention I give a user guide or technical article, so my fingers will often just type what sounds right. And since they all sound the same, you can’t really blame the fingers. For those of you who consistently get it wrong, here are a few tricks to help you remember which form to use without having to think too much.

It’s neither here nor there.

There (usually) references a location. The book is over there on the table. There contains the word here, which also references a location. If you replace there, their, or they’re with here and the sentence still makes sense, then there is the correct word. For example, The book is over ______ on the table. If you put here in the blank, The book is over here on the table, that makes sense, so the correct word is there.

Dude, where’s their car?

Their is a possessive pronoun: their car is the car that belongs to them. Her is also a possessive pronoun. In the sentence, Dude, where’s _____ car, you can insert her, so the correct word is their.

Who’s here? They’re here!

They’re is an easy one: if you’re saying they are, then the contraction they’re is the correct word. The trick for this one, if you really need one, is  Who’s here. They’re here. Who’s is a contraction and so is they’re. Or, using our tricks for there and their, Here here doesn’t make any sense (in this context) and Her here sounds like a toddler, so they’re must be correct. There’re is also a contraction, for there are. If in doubt, take it out (the apostrophe)!

Let us review:

  • It’s neither here, nor there. If you can replace the word with here, use there.
  • Dude, where’s their car? If you can replace the word with her, use their.
  • Who’s here? They’re here. If you mean they are, use they’re. (Or don’t use a contraction.)

The main point is to review what you’ve written before you send/publish it. (I’m sure I’ll find all of my errors tomorrow.)