technical writing | Technical Communication at UAHuntsville

Posts Tagged 'technical writing'

How to Write an Effective Conclusion in Three Somewhat Easy Steps

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 Writers? We Don’t Need No Stinkin’ Technical Writers. Oh, Wait…..

Published November 22, 2013 Jobs , NASA Leave a Comment
Tags: Gravity, Technical Communication, technical writer, technical writing, why hire a technical writer

Imagine: A quiet day at the office. Working away, on-target and on time, when suddenly the universe hurls a supermassive monkey wrench into your plans. All you can do is scramble to adapt. There’s no one there to help you. No one there to guide you. And it’s life or death because “your office” is… SPACE!

Sound like the plot of the latest Hollywood blockbuster? Well, it is. We can all relate to this situation from Gravity, the latest movie starring Sandra Bullock. We’re in the middle of an important task, we’re alone, and technical problems arise. What’s a user to do? We consult the manual!

Who writes this stuff, anyway?

User manuals are not generally known for ease of reading. No one I know takes them to the beach or on vacation as a pleasure read. And yet we have them. We have them because we need them. But who actually writes these manuals? In recent years, some in the technical communication industry have noticed a trend toward Subject Matter Experts (SMEs) as technical writers. A recent internet search for technical writing jobs reflects this trend. Requirements include “Bachelor’s degree in Computer Science/Engineering or a related technical discipline,” “Bachelor’s degree and five years work related experience or a Master’s degree and one year work related experience in a relevant technical discipline,” and “Bachelor’s degree (in related technical field) or equivalent, and zero to two years of related (technical writing and copy editing) experience.” It would seem the “writing” part of technical writing is taking a back seat to the technical aspect. While knowledge of the topic is certainly important, knowledge of writing, specifically the methods and theories of technical writing, cannot be overlooked.

In space, in the office, or at home (SPOILERS)

In Gravity, Bullock plays Dr. Ryan Stone, who finds herself alone and faced with the need for knowledge of complex equipment. What does she do? All her other resources have been cut off – her communications with NASA have been lost and (SPOILER ALERT!) all the other astronauts are dead. So she gets out the manual, just like any user would do. And, voila! She’s alone no more. It’s as though she has a technical writer with her.

Dr. Stone’s best chance of getting back to Earth alive is to pilot a Russian Soyuz capsule from the International Space Station back into Earth’s atmosphere. Piece of cake, right? Sure, until that monkey wrench enters orbit. How about a ship that’s out of gas AND has a dashboard written in Russian (which she doesn’t read)? Luckily for Dr. Stone, there’s a manual in English. Assuming that manual is accurate, easy to follow, and well organized, she should be home free! (This is where we hope NASA hires good technical writers, or she’ll never make it home.) The craft of a technical writer – conveying the right information, and only the right information, when, where, and how the user needs it – is what she’s counting on now. Whether at home, at work, or in orbit, all users need accessible information that works for them in their specific situation – even a situation like Dr. Stone’s, that the technical writer probably never dreamed of.

User Needs — in Space and on Earth

Dr. Stone has a task she must complete; like most users, she dips in to the manual, finds the information she needs, and dips out again. Most do not read the entire manual. (Ron Byrne offers insight into why in the HCi Journal of Information Development.) Even though some users (like Dr. Stone) may have been trained on the product or a version thereof, situations arise where very specialized information is needed. Information that can take a user

from this

to this

or from this

to this .

Who can best convey this information? I vote for trained technical writers. Chunking, relevance, consistency, and hierarchy – these are ideas that technical writers have thought about, are experienced with, and know how to execute. (More on these components of information mapping on the TechWriter Wiki and I’d Rather Be Writing.) Others have argued that technical writers are necessary for clarity and to reduce costs, to act as user advocates, and as usability experts. Add to that someone whose documentation can get me home in one piece – or just help me make the printer work – and it’s clear. Technical writers? Yes… we do need them.

– Mandy Hughes

Writing for Search Engines: Demystifying SEO

Published November 1, 2013 Definitions Leave a Comment
Tags: keyword research, Search Engine Optimization, SEO, technical writing, user-friendly

SEO may seem like just another confusing acronym, but it is not as complicated as it sounds. Search Engine Optimization (SEO) is simply a fancy term for adapting the content of a website so that it will appear higher in search engine results.

Whenever someone types a term into a search engine, that engine’s web crawlers or “spiders” (cue an image of the robot spiders hunting for Tom Cruise in Minority Report) scan the web looking for sites relevant to that term. Fortunately, we don’t need to crack the complex search algorithms involved in this process (but you can read Google’s enlightening explanation of “How Search Works”). There are some basic guidelines that can be followed to ensure that your content, or the online copy that you’re writing for your boss, will appear higher up in the search results.

Choose, and use, relevant keywords

This may be the simplest and most well-known SEO technique. Is your blog about cooking? Make sure you write with words that people will use when they search for topics related to cooking. You may be tempted to employ cutesy titles such as “A Bowl of Cheesy Goodness,” but a more straightforward title such as “Broccoli Cheese Soup for Cold Winter Days” is more likely to show up when your readers search for “broccoli cheese soup recipe.” Also, be sure to think of possible alternate search terms, such as “chocolate icing” for “chocolate frosting.” If you’re having trouble choosing good keywords, then consider using a site like wordtracker.com

However, there is such a thing as too many keywords. Search engines now employ algorithms to detect “keyword stuffing.” The best away to avoid keyword stuffing is simply to write well. Write in a conversational, natural fashion, instead of trying to repeat the same word as many times as possible. This will enhance the experience for your reader, as well as keep your page from being labeled as spam.

Being connected through links

In a world that thrives on social media and other forms of online connection, it is no surprise that having a popular, well-connected website will increase your search engine visibility. A moderate amount of relevant links on your site will rank well with search engines. Internally, you can link to your own content. For example, whenever you reference information that you have posted about previously, link back to that page. When giving your reader instructions, such as how to buy your company’s product, provide links to the different parts of the process.

Outbound links are also important. Links to other well-designed webpages about the same topic show that your site is thorough and well-informed. When other pages start linking to your webpage, that is even better, because now you are being identified as a reliable source. The better connected you are, ingoing and outgoing, the more visibility you get and the more the search engines are going to like you.

I know you love my headings… Well, Google search does too.

Good site organization is important for multiple reasons. It arranges your content in a way that is easier for the reader to follow and consequently, that makes it easier for the search engine spiders to find what they’re looking for. Instead of writing your page in essay format, dump those MLA-style transitions and use headings to organize your information. This is also a great, non-spam-y way to boost your keyword count. Breadcrumbs and a sitemap are other ways to make your site easy to navigate, and they also increase the number of internal links on your site.

Search engines: A new kind of user

SEO is really just another type of technical writing. At its core, technical writing seeks to communicate information to users in an understandable way. SEO simply adds a new user to the mix: the search engine. And as you optimize your content for the search engine, you are improving your content for your human readers too. After all, these three basic guidelines encourage you to write well with relevant vocabulary, be well-informed and well-connected to other sites that support your information, and organize your content effectively. What could be more user-friendly than that?

-Marianne Goodlin

Are the Technical Writer’s Job Prospects Good?

Published October 19, 2013 Jobs Leave a Comment
Tags: technical writer, technical writing

As an aspiring technical writer, I haven’t been aloof to how technical writing—in practice—is changing from what it—in theory—is often presented to be in much lay and sometimes academic literature. And this is a serious issue to me and to those who are in the same boat. It is not apparent that the apparent changes confronting the traditional technical writer are positive changes that will work to the benefit of the education and experience of those ready to enter the workforce. The case for pessimism can indeed seem strong.

To be sure, there are reasons why things look dreary for the technical writer. This was on no greater display than when a class of we technical communication students spent a few moments exploring job postings for technical writers on the internet. Our conclusion: the jobs were there if you are skillful with the English language and Microsoft Office—and if you were familiar with a certain software suite other than Microsoft Office (who knew in advance what that would be?), and were familiar with hardware, and Department of Defense standards of publications, and knew how to work with a mark-up or programming language, and so on.

Consider that Diane Martinez and colleagues in their widely-used and referenced book, Technical Writing, spend the bulk of their time discussing topics like “purpose, audience analysis, and context,” the “forms of technical writing” (e.g., e-mail, memos, and business letters), how to approach research, and how to write grants and proposals. Gerald J. Alred and colleagues in the likewise well-known Handbook of Technical Writing emphasize such topics as forms of documents (a la Martinez), considerations for design and visuals in one’s documents, job searching, and organization. Now all these topics are critical to the education of tomorrow’s technical writer, but notice how centered they are on matters of language, style, and context with precious little in the way of guidance about all the other knowledge, skills, and abilities that we noted are now being demanded by today’s employer.

In acknowledging the disparity between what technical writers are taught and what employers actually want, and agreeing this deserves some attention by our educational institutions, it’s worth noting that recognition is growing that employers can be unrealistically demanding of applicants: Back in 2011 Peter Cappelli wrote a piece for the Wall Street Journal where he noted, “With an abundance of workers to choose from, employers are demanding more of job candidates than ever before. They want prospective workers to be able to fill a role right away, without any training or ramp-up time.” This year, he’s still beating the drum where on the HBR Blog he writes this insightful tidbit, “Some of the cost-cutting took out recruiters. They used to be the people pushing back on hiring managers, asking “do you really need someone with a graduate degree to do this job?” or telling them, “you aren’t going to find someone with 10 years of experience at that salary.”” As post–recession-recovery realism sets in for employers who cannot fill their positions, I suspect the intimidating demands will become more reasonable.

That said, technical writers—aspiring or otherwise—should be on the lookout for continuing education opportunities that are being held in their area. A simple search on the internet can give you information about local opportunities; this especially applies if you live near a college or other institution of higher learning. Also reassuring is O*NET’s projection that technical writing is expected to grow at an average pace—some 10%–19%. Perhaps we ought not be so pessimistic after all.

— Dane Parker

Technical Communication at UAHuntsville