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!

Advertisements

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:

Exactly12ptPict

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:

ParagraphExactly

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:

WholePic

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!)

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 http://www.uxmatters.com/mt/archives/2010/04/user-generated-content-embracing-social-networking-to-deliver-more-engaging-technical-documentation.php:

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?