Technical Writing | Technical Communication at UAHuntsville

Archive for the 'Technical Writing' Category

Well-designed user help takes consumer from concerned to confident

Published November 27, 2017 Technical Writing , usability Leave a Comment

There are a variety of reasons for purchasing a new printer, but a likely one is that your old one has just kicked the bucket, leaving you in a jam with a project awaiting completion. This, of course, means you might be a bit agitated as you head out in search of a replacement.

Before leaving, you might read reviews of printer models online. That does not help your mood as people write mostly about problems and disappointments. But, with an idea of the features you want, some brand names, a price range, and low expectations, you venture off to a retailer and make a selection. After you bring the machine home, the goal is to get back in business independently, with no problems, and complete your project.

A couple of years ago, this was my situation, and I purchased a Canon Pixma MX452 All-In-One (printer-copier-fax machine). Now, I am far from tech-savvy, and I was worried because the online reviews were less than stellar. However, it turns out that setup was a breeze. (So much so that recently I bought another Canon printer for my college-bound son.) Within 30 minutes — and with what seemed like little effort on my part — the printer was “talking” to the desktop computer, the iPads, and the kids’ school laptops. Wow, did my mood — and confidence level — change for the better.

Where to Start

The key to my satisfaction was the Canon “Getting Started” guide. This document describes the steps needed to physically set up the printer, start the control panel, and get it communicating with computers through a wireless connection. Find the document online here: http://www.manualsprinter.com/manuals/canon/Canon_PIXMA_MX452.pdf

The guide is effective because it uses an obvious title, detailed illustrations, just enough language, well-ordered steps, and a commonsense layout.

Starting with the title, “Getting Started” seems adequate to indicate this is the first guide to read, and to ensure consumers don’t launch into one of the other three pamphlets that come in the box. The guide also says “Read me first!” at the top, and it has the e-mail address and the toll-free number for tech support as the first paragraph. That is a convenient place so you don’t waste time looking all over the guide trying to remember where you saw that information. Figure 1 below shows the features I describe here.

Figure 1: The cover of the guide makes clear where to start and where to get technical help.

Well-described illustrations

The guide is clear and simple, with few colors but detailed illustrations. Most importantly, there is enough wording to adequately describe the action in the illustrations. Sometimes, in an attempt to be multilingual, user guides rely too heavily on illustrations and do not have verbiage to clarify the actions (reference some kids’ meal toys, which, made for a worldwide audience, do not include words in the assembly instructions). This guide has just enough wording.

Steps and substeps are clearly numbered, with one sentence for each step. In each black-and-white illustration, the part of the printer that is being addressed is emphasized in gray. In cases where a detail is small, there are zoomed in boxes showing what cannot be seen, down to the shape of a plug. See Figure 2 below.

Figure 2: Zoom-in boxes show hidden details

The guide is readable and not cumbersome, partially thanks to the fact it is printed in just two languages, English and Spanish. When multiple languages are accommodated, the type size tends to get very small and the paper gets quite large, like a car map that you can never fold correctly again.

Makes no assumptions

The layout has an orderly flow, so you can tell where to start and where to look next. In addition, the guide does not presume that a user has set up a printer before or that a user might understand a direction because he or she has done it in the past. Every step is explained with illustrations and words, including tips that are highlighted in pink.

Tips might try to prevent you from doing something you might assume is the next step. For example, Step 1.5 says, “Connect the power cord.” Then it says, “Do not connect the USB cable yet.” Or they might give more detail about what you see. For example, Step 1.7 says, “Select your language then press the OK button.” Then it says, “To change the language setting, press the Back button.”

Once the actions in this guide are complete, the final step instructs you to insert the CDROM into the computer and follow the onscreen directions to complete set-up. Installing the software takes just a few minutes and you are back in business. (For computers or laptops that don’t have a CD player, you go online to complete set-up.)

This Canon Getting Started Guide certainly can be a role model for other guides. It keeps the home user in mind, with simple sentences that adequately describe the action in the illustrations. The physical size of the guide is manageable and not convoluted by too many languages, and the layout progression is clear. This guide made me a happy, confident consumer.

By Deborah Bennick, EH-501, Oct. 15, 2017

Plain language! Simple tips to make your content more accessible

The UN and the World Bank says that 10% of everyone in the world has a disability of some kind. That is a lot! And in addition to that when we get older, over 30% of us will have some disability. These numbers show that thinking about accessibility when writing and designing our content is extremely important. The first questions that should pop up in our heads are: Will my audience find what they need? Understand what they find? Act appropriately on that understanding? There are many reasons why people have trouble reading: cognitive problems, low literacy, physical or vision disabilities, or reading in a second language. But even proficient readers can have problems reading if they are rushed, stressed or tired. You should write in plain language and present your content clearly and flexibly to make it accessible. But how can you do so? Here are some useful tips:

Think about your audience first

Know your audience and make your content suitable for them. You should know what your audience needs. Writing in plain language doesn’t mean dumbing down the content, but making it clear by getting straight to the point.

Make your information easy to understand, even in poor conditions

Keep in mind that not everyone will read every word you write. People are usually in a hurry or multi-tasking. They also read in places that make reading difficult such as poor lightning or on electronic devices with tiny screens. Your content should be easy to scan through! Use topic sentences to introduce the subject of your paragraph before going into details. Also, keep sentences short and concise: avoid the passive voice and use simple and clear verbs.

Your content should be easy to translate

English is the international language. Many readers are non-native English speakers. Make your information easy to translate. Write simply by using words that your readers will be familiar with.

Use lots of headings

Create meaningful headings for each section. Useful headings should communicate the key points of your content, helping readers scan and find the information they need. They can be questions, statements or topics.

Talk to your readers

Get personal and talk directly to your audience. Talking directly to your readers makes a better conversation. People tend to pay more attention if you are referring directly to them. Use “you” and the imperative to give readers instructions.

Be organized

Put the sections of your content in a logical order from your readers’ perspective. Start with the information they need first. Use bulleted lists or tables to make it easy for them to scan through your text and find specific information.

Be visual

Many people understand information better through images. Use images that illustrate concepts and give them an alternative text or captions. Information graphics and animations showing processes and relationships are also very helpful.

For more information, check out:

http://www.plainlanguage.gov/

http://centerforplainlanguage.org/about-plain-language

Source: Horton, Sarah, and Whitney Quesenbery. A Web for Everyone: Designing Accessible User Experiences. Print.

Sarah Bastos

How to Write an Effective Conclusion in Three Somewhat Easy Steps

Published October 18, 2014 Technical Editing , Technical Writing Leave a Comment
Tags: technical writing, writing

Imagine the following scenario and ask yourself: how many times have I been in this position? It’s almost midnight, the night before your term paper is due, and you’re stressing over the last minute details. All the information organized in a logical way? Check. Correct spelling and punctuation? Check. Sources cited properly? Check. Then you realize…“oh no, I still haven’t written the conclusion!”

Raise your hand if that sentence has passed through your head at one point or another, because let’s face it, writing a conclusion is a pain in the neck. Whether it’s a short paper for class or your first proposal after starting work at a new company, the conclusion is always the section of the paper that you put off writing for as long as possible. Seriously, how are you supposed to sum up, say, your 200-page dissertation in just a few paragraphs?

Here’s how.

1) Ask the question, “so what?”

Your conclusion shouldn’t ask and answer the question, “what is this?” Hopefully, the rest of your paper has already done that. Rather, ask the question “so what?” meaning ask yourself, “why is this information important and why should anybody care?” This is particularly effective if you’re a technical writer finishing up a document; you’ve just spent x amount of pages describing your product, but it won’t do much good if the audience is still unsure about buying it. Use this as a chance to make them sure.

Use the Socratic Method when thinking of how to form your ending statements. Play out a little dialogue in your head between yourself and the potential reader. If the reader asks why your argument is relevant, have a definitive answer ready and waiting. If the reader picks out a flaw in that argument, find a way to back it up. Remember, your conclusion is your last chance to make the audience realize why your points are valid. Make it count!

2) Restate your thesis.

This is where things can get tricky. First of all, reiterate your thesis, but don’t say exactly the same thing you did in your introduction. Find a way to rephrase the original statement, including some examples previously used in the paper. Synthesize your main points and show how they form a cohesive argument – explain why everything fits together. Think of your paper as a jigsaw puzzle and your conclusion is the final piece that anchors the rest of them. In doing so, you are able to not only sum up your points without being redundant, but also show your audience that you care enough about your argument to give it a good ending and not take the lazy, copy-and-paste-the-original-thesis approach.

3) Connect the topic to broader themes

This is a good way to get your audience involved in the discussion. Ask a question about your topic and then propose a solution, apply the information to something else of relevance. For instance, if you’re writing an analysis on The Adventures of Huckleberry Finn, then give examples of how that novel has influenced others in contemporary American literature. Likewise, if you’re writing a scientific paper, then elaborate on how the discoveries made could impact future studies. Make your audience think about how your argument connects with others like it, and in doing so, potentially discover the topic for your next paper.

And there you have it, folks: three steps for how to write an effective conclusion. It’s one of the hardest and most nerve-wracking things to write, especially if you’re a proposal writer and any part of the given proposal could determine whether or not your company gets the bid. So bear these tips in mind the next time you sit down at your desk at midnight the night before the assignment is due. Because to your teachers, the idea of a weak conclusion is totally and completely…

For more information, visit http://writingcenter.unc.edu/handouts/conclusions/

Thanks for reading!

Erin S. O’Reilly

Proofing in a pinch

Published September 20, 2014 Technical Communication , Technical Editing , Technical Writing Leave a Comment
Tags: editing, proofreading, technical editing, technical writing, writing

Are you stressed out because you have a document or project due soon and you were not allocated enough time for proofreading? So now you are under a time crunch, right? Luckily for you, I have a solution to your problem. This quick fix will help you correct some of the most common mistakes found in technical writing. Think of this blog post as you would SparkNotes; as an analogy of sorts: SparkNotes is to a novel as “Proofing in a pinch” is to proofreading. This guide is an immensely abbreviated version of proofreading, but these few easy steps will undoubtedly come to your rescue the next time you find yourself with too little time to do too much correcting.

Step 1. Spelling

With all of the awesome spellcheck tools, who can mess this up, right? However, one of the most overlooked spelling mistakes I have seen during my several years of experience of document writing and editing is incorrectly spelling or improperly referring to the company’s name. Writers often overlook this because we are too preoccupied with the main content of the document, refusing to properly recognize the most important detail—the company. The following cases are where spellcheck might become a hindrance rather than a benefit.

Example

The Law Office of J. Shay Golden wants Margaret, a technical communicator, to draft a brief. Margaret drafts the brief within one week and hand-delivers it to the partner at the firm.

Case 1

Margaret referred to the firm as “The Law Office of J. Shea Golden” throughout the brief. Unfortunately, Margaret relied on the spellcheck tools, which accepted both “Shay” and “Shea” as correct spellings.

Case 2

Margaret referred to the firm as “The Law Firm of J. Shay Golden” throughout the brief.

Unfortunately, the spellcheck tools are not equipped to check for consistency and correctness when referring to the employer’s company’s name.

Imagine the embarrassment Margaret faced when the mistake was brought to her attention. Always, always go through your document and double-check the spelling and accuracy of the company’s name. This should be the first step in your prompt proofing process.

(Photo credit: Grammarly; http://www.grammarly.com/blog/2014/please-stop-making-this-mistake-thank-you/)

Step 2. Punctuation

Contractions. Rule of thumb—never use them. These are those words we use to simplify our language in conversation and informal writing, such as can’t, we’re, and should’ve. The simple solution to checking for contractions in a document is to scan each page for an apostrophe [‘]. When you find one, the first thing to do is to determine if it is being used to form a contraction or a possessive. If it is a contraction, remove it and extend the contraction into the subject and the verb. (Fun fact of the day: the apostrophe is used in a contraction to indicate the omission of a letter, or letters, in one of the words.) If it is a possessive—leave the apostrophe alone. It is supposed to be there. However, if you are using an apostrophe in a word that should be pluralized then you need to review your rules here: http://www.grammar.cl/Notes/Plural_Nouns.htm

(Photo credit: Grammarly; https://www.facebook.com/grammarly)

Periods and Commas. Always scan through your document and make sure that these are used correctly. The last thing you want to do is submit a document with a mistake so elementary as a missing period or a comma. To check for absent periods, quickly scan through each sentence and check that it begins with a capitalized word and ends with a period (be sure to double check the more complicated sentences that contain those tricky semi-colons). As for commas, they can make all the difference in the world, so they might require a bit more attention at the word-level during proofing. Therefore, you can review grammatical rules here in case you are a bit rusty: https://owl.english.purdue.edu/owl/resource/607/02/

(Photo credit: whisper down the write alley; http://whisperdownthewritealley.wordpress.com/2012/09/22/punctuation-matters-commas-save-lives/)

Step 3. Figures, Tables, and Headings

I mentioned consistency before. This is especially important when it comes to this next topic: figures, tables, and headings. As always, you should follow the company’s style guide and preferences (hopefully, these would have been consulted before the writing began), but because you are caught in a pinch for editing, trust the writer and simply go through the document and ensure that all figures, tables, and headings conform to the same format.

Conclusion

Technical writing and editing is a very intricate process that requires much time and effort. It also requires great attention to detail. But when time is of the essence, following these rules will undeniably ensure your work does not contain those pesky, embarrassing mistakes that all professional writers make, yet hope to avoid.

—

Thanks for reading!

Kala Burson

Technical Communication at UAHuntsville