The Art of Technical

WritingBased on the slides and book

From Idea to Print: How to Write a Technical Book or Article and Get It Published

by Roger E. Sanders. Used with permission.

Susan Visser @susvis

Objective for York U Students

The idea behind this training is simple:

You have been asked to write three technical reports and a paper for this class. The reports must be 3-8 pages in length and the paper 15 pages. Your paper must include an abstract, introduction, conclusion and bibliography.

I’m here to give you some advice to make these reports the best they can be to maximize your marks.

2@susvis

Why Write?

• To pass a course / graduate

• To communicate ideas to others

• To become a domain expert

• To better understand the domain

• To stand out – get noticed, promoted, and get paid more!

3@susvis

Types of Technical Writing

• Blogs (typically 200 words or less)

• LinkedIN, WordPress

• About Technical Blogging

• Sam Lightstone on Careers

• Chris Eaton on Databases

• Articles or tutorials – for example on developerWork or IBM Data Mag

• Books – example: Free Flashbooks from 2014

4@susvis

• In academia:

• Technical reports, theses, essays, school assignments, and white papers: YorkU

• And beyond:

• Blogs, Articles, Books

Table of Contents & Outline

5@susvis

• Develop a detailed Table of Contents outline before you begin the actual writing process.

• A good Table of Contents outline should serve as your blueprint when you begin the actual writing process. As you develop your TOC outline:

Think about who your audience is.

Think about the message you are trying to convey.

Cover topics in a logical, naturally progressive sequence.

Use lots of headings and subheadings.

• Knowing your book’s scope, purpose, and audience will help you identify items that need to be covered and items that don’t belong.

GET RID OF

ANYTHING

THAT DOESN’T

BELONG

Control the Writing Process

Adhering to your Table of Contents outline during the writing process will help

you create the report you envisioned. If, as you write, you find your report

evolving in ways you never anticipated, go back and adjust your outline. Be

prepared to throw out material that is outside the new scope.

Use headings and subheadings to organize the text and break it into readable

units.

@susvis 6

For the best results, write in a random order. (Write your introduction/abstract last!)

Abstract

• The abstract is the most crucial part of the report because anybody searching for your research on a database or in a journal will usually read only the abstract. Therefore, it must summarize your research, results and conclusions in less than 200 words. Sometimes it is good to think of it as a sample of your research rather than a review; it should inform the researcher that your article contains the information they need.

• There are a few ideas on how to write your abstract but the best advice is that you look at some journals relevant to your research and try to format your abstract in a similar way.

• Read more: http://www.experiment-resources.com/research-paper-outline.html#ixzz1G7jIIucp

7@susvis

Introduction

• This section of your report is where you will document all the painstaking research into the background of your experiment. The main thing to bear in mind, when writing the introduction, is that a scientist who is unfamiliar with your exact subject matter may be reading the article.

• It is important, therefore, to try and give a quick and condensed history of the research leading to your experiment, with correct citations.

• You should also give a little background on why you chose to do this particular experiment and what you expect to find. It is a little ‘old-fashioned’ to place your hypothesis statement at the beginning of the report but the reader should be aware of exactly what you are trying to prove.

• Read more: http://www.experiment-resources.com/research-paper-outline.html#ixzz1G7k5TVh1

8@susvis

Conclusion

• This is really just a more elaborate version of the abstract. In a few paragraphs

you should summarize your findings. Your abstract will do most of this for you

but, as long as you do not get carried away, especially for longer reports, it can

help the reader absorb your findings a little more.

• Read more: http://www.experiment-resources.com/research-paper-

outline.html#ixzz1G7kje67u

9@susvis

Bibliography

• For any research paper, writing a bibliography is essential, to prevent any accusations of plagiarism, and to give fair credit to the work of previous authors in the field.

• Writing a reference-list also allow the reader, or the person marking the paper, to check the original sources if they require more detail.

• Your bibliography, often called a citation list, always comes at the end of the paper, and it must include all of the direct sources that you referred to in the body of the paper.

• For the vast majority of scientific papers, APA or MLA style references are used, alphabetically ordered by the surname of the author. For any sources with no author, use the name of the organization or website or, if there is no other choice, use the title of the work.

• As with in text citations, it is important to stick to one style and avoid confusing the reader.

• All entries in the bibliography should be in alphabetical order, and they should use a hanging indent.

• If you use more than one source from the same author, you should order them by date and then by the first letter of the title, if the year of publication is the same.

•Read more: http://www.experiment-resources.com/writing-a-bibliography.html#ixzz1G7kwBIPD

10@susvis

Writing is hard work

Writing is a rewarding task, but it requires a great deal of time, self-discipline, and

attention to detail. Writing is also hard work:

“If you find that writing is hard, it’s because it is hard.”

William Zinsser: On Writing Well

To be a successful writer, you need to schedule time for writing and then stick to

that schedule. This may sound like common sense, but common sense often takes a

back seat to the demands of day-to-day life.

11@susvis

Common excuses for not writing

It has been said that there are two great flashes of inspiration in the process of

publishing a paper/book – the first comes when the project is conceived and

the second when you finally hold a copy of the finished product in your hands.

These are separated by a long, and seemingly endless time of writing.

Somewhere along the way, the inspiration fades and it gets easy to find excuses

not to write.

12@susvis

Excuse 1:

“It takes a special talent to write.”

Writing is a skill, not an innate gift or a special talent. Like any advanced skill, writing is a skill that must be developed. If you want to become a good writer, you need to:

Read as much as you can. Reading exposes you to a wide variety of writing styles and gives you a chance to see how others have composed sentences, paragraphs, and chapters.

Attend classes and/or read books on writing. There are plenty of books on writing available. York U offers writing workshops. Just keep in mind that while both can provide you with information on how to write, neither can make you a good writer.

Practice, practice, practice. In this case, the old saying “Practice makes perfect.” is true. Try to write every single day – even on the days you don’t really feel like writing.

13@susvis

Excuse 2:

“I can’t find time to write.”

If you think that you won’t be able to write until you get a big block of free time, then you’ll never write a lot. Finding time is a destructive way of thinking. Instead of finding time to write, you have to make time.

Prolific writers make a schedule and stick to it. It’s that simple.

Each person will have their own “best time for writing,” given personal commitments. It doesn’t matter if you pick one hour a day every day or four hours a day, twice a week. The key is the regularity, not the number of days or the number of hours set aside for writing.

When you sit down to write, eliminate all distractions. (Block off your cube, mute the phone, block off time in your calendar, etc.) This is your time to write – not to watch TV, answer email, or play computer games.

14@susvis

Excuse 3:

“I need to do more research first.”

While its true that technical writing requires some amount of research and testing,

don’t fall into the trap of doing nothing more than research and testing.

Your research should include idea generation, reading, outlining, and any data

analysis that is needed to generate text.

15@susvis

Excuse 4:

“To write a lot, I need ____ .” (Fill in the blank.)

“In order to write, all a man needs is paper and a pencil.”

William Saroyan

Some writers complain that they can’t write because they don’t have a fast computer. Others complain that they don’t have fast internet access, or a good laser printer. These are all just poor excuses for not writing.

The reality is that all you really need to write is a basic computer, some kind of word processing software, and somewhere to sit.

Be sure to save your work and make backups!

16@susvis

Excuse 5:

“I need to be in the right mood to write.”

In a study conducted in 1990, it was found that individuals who were forced to write during 50 scheduled time periods produced 3.5 times as much material as individuals who attended the same 50 periods but only wrote when they felt inspired to. Furthermore, forcing people to write enhanced their creativity – the number of days between creative ideas was 1 day for people forced to write and 2 days for those who waited to be inspired.

The truth is that some kinds of writing are so unpleasant that no normal person will ever feel like doing them. Successful writers are prolific because they write regularly, usually every day, whether they feel like it or not.

17@susvis

A word about binge writing

When it comes to writing, many people use a wasteful, unproductive approach called binge writing. After intending to write, procrastinating, and then feeling guilty and anxious about procrastinating, binge writers finally devote a day or two to nothing but writing. This creates some text and alleviates the guilt, but then the cycle begins again.

Binge writers spend more time feeling guilty and anxious about not writing than they spend writing.

Don’t be a binge writer!

18@susvis

Setting goals

To write a lot, you need to set writing goals. As with any good goal, writing goals should be finite and measurable.

If you are writing every day, your daily writing goals might look something like this:

Write at least 200 words.

Write the first three paragraphs of ______.

Complete section ______.

Incorporate reviewer comments into ______.

Review copy edits and address suggested changes.19@susvis

Monitoring your progress

Most people have no idea how much – or how little – they are writing. Most people

think they are writing more often and more efficiently than they really are. To write

a lot, you need to monitor your writing progress as accurately as possible.

Behavioral research has shown that self-observation alone can cause the desired

behavior. Thus, the process of monitoring your writing progress will actually help

you sit down and write more.

20@susvis

Reward yourself

• “Self-reinforcement and contingency management are time honored ways of fostering desirable behaviors.” - B.F. Skinner from Upon Further Reflection

• When you complete a small goal, treat yourself to something special – maybe a dinner at your favorite restaurant or a movie you’ve been wanting to see. When you finish a large goal such as the completion of a book, buy yourself something you have been wanting for quite some time.

• Never reward small goals with time off from writing. That’s like rewarding yourself for quitting smoking by having a cigarette.

21@susvis

A word about procrastination

Procrastination is a complex psychological behavior that affects everyone to some degree or another. With some it can be a minor problem; with others it can be a serious issue.

Procrastination is only remotely related to time management, which is why having a detailed schedule to follow usually does not help. (Procrastinators often know exactly what they should be doing, even if they will not do it.)

If you find that you are procrastinating when it comes to writing:

Realize that your feelings govern your motivation. If you have negative feelings about writing, you will tend to put off or delay a writing task.

Explore the real reasons for your desire to put the work off. List your reasons.

Dispute those reasons and overcome them. (Most times you will find that your reasons are just poor excuses.)

Force yourself to begin.

22@susvis

Ways to work through procrastination

Make the task look small and easy in your mind.

Do only a small part of the task each time you work on it.

Try using the five-minute plan - work on something for just five minutes. At the end of five minutes, switch to something else if you want. (Chances are, you'll get involved enough to keep going.)

Advertise your plans to accomplish something, and let peer pressure push you forward.

Modify your environment - if you can't write while someone has the TV on, move to a location where you won’t hear the TV.

Plan out tomorrow and establish priorities - some people find that simply writing down reasonable starting and stopping times helps them get going.

Expect some backsliding. The best laid plans don’t always work out. Accept setbacks and try again.23@susvis

Elements of technical writing

The primary goal of any technical document is to transmit technical information accurately. Because of this, many technical writers focus on providing content and give little thought to technique. But, when the following elements of writing are applied, a technical document becomes much more than just a bunch of facts:

Organization Composition

Wording and phrasing Tone

Bias-free wording Tables and illustrations

Permissions

24@susvis

Rules for organization

How you organize material – that is, how you choose what goes first, what goes

second, what goes third, and so on – determines, to a large extent, whether you

effectively communicate your main points to your readers. A few basic rules for

organizing writing are:

Organize your material according to the way your reader thinks about the subject

Organize your material logically Use headings and subheadings

Separate fact from opinion End with a strong closing

25@susvis

Organize your material according to the way your

reader thinks about the subject

Most people will not read a document that does not hold their attention.

To gain and keep your reader’s attention, you need to tell the reader what they want (not what you want to say). And you need to organize your writing according to the way the reader normally thinks about the subject.

The best way to organize your writing is to know who your audience is, their main concerns, and how to get their interest.

Creating a detailed Table of Contents outline can help you organize your material so that it is reader oriented. The main advantage of this approach is that it helps organize the information you plan to present before you begin the writing process.

26@susvis

Organize your material logically

If you are unsure as to how your reader thinks about the subject, choose an organizational structure that logically fit the material.

• Alphabetical order Priority sequence

• Chronological order Problem/solution

• Inverted pyramid Deductive order

• Inductive order

• List

27@susvis

Use headings and subheadings

Headings and subheadings serve several purposes:

They break the text into short sections, which makes the material easier to read and digest.

They provide quick reference points to help the reader quickly locate specific information.

They enable the reader to locate key points without reading the entire document.

Each section of your document that is separated by a heading or subheading should cover a single concept or major thought. When you’re ready to cover a new topic, write a new heading/subheading and start a new section.

Whenever possible, keep your headings/subheadings consistent and parallel.

28@susvis

Separate fact from opinion

Technical writing is meant to clarify rather than confuse, to present a point of view supported by reason rather than force an idea or concept upon a reader.

Why is it important to separate fact from opinion in technical writing? Because often, your readers will make business decisions based on the information contained in your document.

How do you separate fact from opinion? One technique is to divide your document into sections with headings that indicate whether each section contains facts or opinions.

Another way to indicate an opinion is to preface it with the phrase “In my opinion.” But be careful when using this phrase and others like it – depending upon your audience, it can either confirm accuracy or give the impression that you are avoiding responsibility.

29@susvis

End with a strong closing

Strong documents are often ruined by weak closings.

Not knowing how to close, writers often throw together two or three paragraphs

that say essentially the same thing in three or four different ways to make sure the

reader gets the message.

Decide how you want to close, say it once, and then get out. Be original and direct

– don’t fall back on clichés, or stock phrases.

30@susvis

Principals of composition

The term composition, in writing, refers to the process and study of creating written works. Some principles of composition that can help you present your ideas in a lively, authoritative, and original manner are:

Use the active voice Use simple language

Avoid long sentences Use specific and concrete terms

Write in a natural, conversational style Keep ideas and sentence structure parallel

Provide smooth transitions when changing topics Break your writing into short sections

Delete words, sentences, and phrases that do not add to your message

31@susvis

Use the active voice

With active voice, the subject performs the action: Patrick analyzed the results.

The opposite of active voice is passive voice. With passive voice, the subject gets acted upon: The results were analyzed by Patrick.

Active voice makes your writing more direct and your sentences more concise; active voice reflects authority.

• Passive voice often suggests evasion and arouses suspicion. Some people use passive voice as a way to avoid responsibility or remain anonymous. Others use it when they are trying to write in third person.

• Passive voice does have its place. Use it when the person performing the action is unknown or less important than the action itself: The company was founded in 1979.

@susvis 32

Use simple language

The point of writing is to communicate clearly. Using complicated words violates that point and sets up barriers between you and your audience.

Which of these sentences do you prefer?

In reference to the situation in California, there have been certain setbacks that have prevented firefighters from extinguishing the wildfires near San Bernardino.

Or

The news from California is not good. Wildfires continue to burn near San Bernardino.

Using simple language does not mean that you must write to a fourth grade reading level. It means that you present your material in such a way that the least-knowledgeable member of your audiencecan easily understand the message you are trying to convey.

33@susvis

Avoid long sentences

When is a sentence too long? That’s a matter of judgment. A well-constructed sentence can contain over 50 words yet be easy to understand while a poorly-constructed one can contain just a few words and seem endless.

One way to determine whether a sentence is too long is to read it aloud. If you run out of breath, the sentence is probably too long! Another way is to read it to someone else. If the listener gets confused or forgets the idea presented at the beginning, the sentence is too long.

Some lengthy sentences can be can be shortened by eliminating wordy phrases and redundancies. Others can benefit by being broken into two or more smaller sentences (use transitions to tie the smaller sentences together).

Don’t go overboard. If you write nothing but short sentences, your writing can come across as a series of choppy thoughts. Occasionally, you need to combine two or three short sentences together to paint fuller picture.

34@susvis

Delete words, sentences, and phrases that do not add

to your message

Your reader’s time is precious. If you take three pages to say what you could in a

few paragraphs, your reader may not bother to finish reading what you have

written. Or, they may skim it with impatience and miss important points.

So how do you make your writing more concise? Develop a habit of reading over

the first draft of anything you write with a sharp eye for words, sentences, and

phrases that do nothing to convey your message. If you spot writing that takes too

long to get to the point, shorten or remove it.

“Vermont is a state that attracts visitors because of its winter sports.”

35@susvis

Use specific and concrete terms

Specific, concrete terms paint a vivid picture in your reader’s mind. Vagueness makes the picture blurry. For example, the sentence: I need your comments back ASAP. is vague.

It assumes that the reader’s concept of ASAP is the same as the author’s. The following sentence is better because it assumes nothing:

Please review Chapter 3 and send me your comments by Friday.

Writers sometimes use vague terms to gloss over a matter they don’t want to draw attention to. Vagueness is also used when writers assume that a statement will have the same meaning to the reader.

Assume nothing! Say exactly what you mean. Don’t force your reader to probe for specifics or second guess your meaning.

36@susvis

Write in a natural, conversational style

Good writing should sound like normal conversation. Do you talk like this:

If further information is required, you should contact Jim Wentworth.

Or more like this: If you need more information, call Jim Wentworth.

Apply the conversational test to rid your writing of stilted wording, a prissy tone, stiff and

formal phrasing, and jargon that can obscure your meaning or worse, alienate your readers.

Writing with a conversational tone does NOT mean it’s ok to use slang or informal

language. This type of language may work in a novel or screenplay, but it has no place in

technical writing because it usually sets a negative tone.

37@susvis

Keep ideas and sentence structure parallel

Parallel construction clarifies meaning, creates symmetry, and lends equality to each

idea presented. Consider the following sentence: Please fill out this form, sign it,

and then it should be returned to me.

The last item is awkward because it is not parallel with the rest of the sentence. A

better sentence is: Please fill out this form, sign it, and return it to me.

Lists are another area where parallel construction is important; if the first item in a

list begins with a noun, every item in the list should begin with a noun.38@susvis

Break your writing into short sections

A general principle of good writing is to divide your subject into topics and then cover each topic in a paragraph. Another principle is to keep paragraphs short –ideally, a paragraph should be three to seven sentences long.

Not only are short paragraphs easier to read, but research has shown that readers absorb information more easily when it is presented in short, coherent units.

If possible, break long paragraphs into smaller ones, making the division occur where one topic ends and a new one begins. But be careful – make sure the first sentence that begins a new paragraph isn’t more appropriate as the final sentence that rounds out the topic of the previous paragraph.

39@susvis

Provide smooth transitions when changing topics

Transitions improve the connections between thoughts and help your writing flow

smoothly. Consider the following sentences:

Pour a half-cup of milk in the bowl. Add two eggs. Stir the mixture.

With transitions, these three sentences become two, more connected sentences:

First, pour a half-cup of milk in the bowl. Then, add two eggs and stir the mixture.

Transitions are typically used to show conclusion, repeat information, show

comparison, show contrast, show a time relationship, limit, show cause (explain

why), show effect/result, assert an obvious truth or grant opposition.40@susvis

Principals of wording and phrasing

It is important to strengthen and clarify your writing; this enables your readers to

grasp your meaning quickly and without ambiguity. Some principals that help in this

area are:

Avoid wordy and redundant phrases Use small words

Avoid clichés Avoid the use of jargon

Define all acronyms

41@susvis

Avoid wordy and redundant phrases

Expressions like “as you may or may not know”, “at this point in time”, and “in

regard to” use more words than necessary to convey a thought.

Expressions such as “free gift”, “plan ahead”, and “foreign imports” are redundant;

each says the same thing twice. All gifts are free, “plan” implies planning ahead, and

by definition, imports are foreign.

Wordy and redundant phrases muddy your writing, obscure your point, and waste

your reader’s time

42@susvis

Use small words

Generally, good writers prefer small words to complex or elegant ones. Unfortunately, some writers try to impress their readers by using long words or obscure words that few people know the meaning of. If you saw the following sentence:

Bill was known for his malapropisms.

Would you know that when speaking Bill often used the wrong word by mistake? Or would you have to consult a dictionary to find out what Bill was known for?

When you are tempted to use a big word, first ask yourself this: Are you trying to impress or express? The best way to impress is to put big thoughts into simple, everyday language. Not to trot out big words.

43@susvis

Avoid clichés

Clichés are expressions that have been used so often that they have lost much of their original freshness and power. Some examples of clichés include:

• user friendly acid test

• bottom line few and far between

• grind to a halt state of the art

• ballpark estimate first and foremost

• last but not least

People adopt clichés because they are familiar and handy. But the very popularity of a cliché make its impact weak. Consequently, the use of clichés in your writing make the message you are trying to convey weak and boring.

44@susvis

Avoid the use of jargon

Every industry has its set of “buzz words”. These words may be understood by everyone in the industry, but when writers use them to communicate with others who are not in the same industry, confusion sets in.

How do you spot jargon? Unlike legitimate technical terms, which can be looked up in a dictionary, jargon is a private language that only has meaning to a particular group.

It is acceptable to use a technical term if you believe that at least 90% of your readers will understand it. But don’t use jargon unless it precisely communicates your meaning and will not confuse your readers.

45@susvis

Define all acronyms

Acronyms are abbreviations that are formed using the initial components in a phrase or

name and can be pronounced as words. These components may be individual letters (as in

FAQ), and/or parts of words (as in Xerox – which comes from the word Xerography).

Some acronyms may be recognized immediately by your readers; some may not. As with

jargon, when a reader encounters acronyms they are unfamiliar with, confusion sets in.

Never assume your reader will be familiar with every acronym you use!

Whenever you use an acronym, always define it the first time it is used. If you are creating a

book that will have an index, consider creating an index entry for the acronym’s definition.

46@susvis

Achieving the proper tone

Achieving the proper tone is a subtle but important part of good writing. A few rules that can help you achieve the proper tone are:

Write to express, not impress

Opt for an informal style rather than a formal style

Use positive words instead of negative words

In a sentence that contains both good and bad news, give the bad news first

Be your most pleasant self

Use contractions to warm up your message47@susvis

Write to express, not to impress

Instead of writing to impress the reader with your technical knowledge, or mastery

of big words and fancy phrases, write to convey your meaning.

Many writers, especially beginners, feel they have to impress people with their

knowledge of big words and complex sentences. Don’t make this mistake.

Whenever you write a sentence that sounds as if you’re trying to impress the reader

with your knowledge, reread the sentence and extract the key idea you are trying to

communicate. Then, rewrite the sentence in plain, simple English.

48@susvis

Use informal instead of formal language

Many people, especially engineers and technical professionals, mistakenly believe they must adopt a cold, remote, or superior tone to sound “professional” in their writing.

When you write in an overly formal style, you come across as a lawyer or bureaucrat. That’s unfortunate because people would rather deal with a friendly, helpful human being than a lawyer, a bureaucrat, or a cold, impersonal corporation.

Your writing should project a personality that is inviting to the reader, not one that turns the reader off.

When deciding on what tone to take, err on the side of being too informal and conversational. No one has ever complained that a technical document was too easy to read.

49@susvis

Use positive words instead of negative words

Negative words and phrases often convey an arrogant or accusatory tone. For example, the phrase “neglected to” implies willful misconduct; the phrase “lack of ” communicates personal criticism.

When you write, try to address unpleasant matters without offending anyone.

When you want to express a thought in a positive manner, substitute the word if with the word when. For example, the sentence:

If the test results are satisfactory, we’ll change configurations.

sounds more positive when written like this:

When the test results are satisfactory, we’ll change configurations.

50@susvis

In a sentence that contains both good and bad news,

give the bad news first

When you want to emphasize something, put it at the end of a sentence. Therefore,

to convey a positive tone, a sentence should present bad news first, followed by

good news.

Often, the bad- and good-news portions of a sentence are separated by the word

but or the word however:

Version 2.0 of the software won’t be ready for another six months;

however, version 1.6 is still selling briskly and getting rave reviews.

51@susvis

Be your most pleasant self

We all have our ups and downs – sometimes we are in a good mood; at other times we’re short-tempered and irritable. In your writing, you need to be at your best.

Your writing will also sound more pleasant when you use personal pronouns (I, we, you) instead of third person (they, the company).

Don’t be too brief; being too brief can make you sound arrogant or impatient. On the other hand, don’t gush or go on and on. Be direct and to the point.

If possible, always write when you are in a good mood. If you must write when you are irritated or angry, revise what you have written when you’re back in a good mood. Keep in mind that no matter how you try to hide it, your attitude and mood almost always comes through in your writing.

52@susvis

Use contractions to warm up your message*

Contractions (can’t, don’t, won’t) help make writing appear more conversational and informal; their use creates a friendly tone.

Use a contraction whenever you want to achieve a warmer tone in a sentence. It is also a good idea to use a contraction where you would normally use one if you were saying the sentence to someone aloud.

When you want a more remote tone or when you want to add a special emphasis to a phrase, use the written-out form instead.

Although contractions make writing more conversational, don’t overuse them! If you find your writing contains too many contractions, replace some of them with the written out phrase.

53@susvis

Tables

Tables consist of rows and columns of data and often include titles, lines, column heads, sources, and footnotes. In some cases, a table may be the only way to present certain information that is essential to the text.

One drawback of using tables is that readers tend to skip them because the very presence of a table creates an interruption in the flow of the text.

Before you insert a table into your document, ask yourself whether a table is really necessary. If you can summarize the content of a table in the text or present it in some type of list, the reader is more likely to absorb it.

Plan each table carefully for maximum effectiveness and clarity. Keep things simple by arranging column headings such that there is no duplication of entries. Also ensure that all entries in a row or column are presented in comparable form.

54@susvis

Artwork

There is an old saying that a picture is

worth a thousand words. And a well

designed illustration or figure can do

the work of several pages of text.

@susvis 55

Text figures

Text figures include computer program listings and bodies of text such as sample forms and letters that need to be offset from the main text. Use the following guidelines when creating text figures:

To avoid the introduction of errors, test all programs and copy the desired source code directly into the manuscript or illustration software.

As a rule of thumb, treat program listings of less than 5 lines as text; treat program listings of 5 or more lines as figures.

Limit code listings to 70 characters per line.

Use line breaks and spacing appropriately to ensure the code is readable.

@susvis 56

Staying out of trouble

When writing any document, regardless of whether it is technical in nature, you must take care not to alienate or offend some members of your audience. And if you turn to other people’s writing to get ideas on how to present some material, you must be very careful that you don’t end up plagiarizing or infringing on someone’s copyrights.

There are three important things you need to know in order to stay out of trouble when writing. Those things are:

How to write bias-free text

How to avoid making libelous statements

How to avoid plagiarism and copyright infringement

57@susvis

Guidelines for bias-free publishing

When writing technical documents, every effort should be made to prevent

depicting a “biased” representation of something. A few rules that can help you

write bias-free text are:

Use parallel language

Avoid gender-specific terms

Avoid gender-specific pronouns

Avoid stereotypes

58@susvis

Avoiding plagiarism

Using another person’s ideas or expressions in your writing without acknowledging the source (either on purpose or through carelessness) is a serious offense known as plagiarism. Careers and reputations have been ruined because of plagiarism and copyright infringement. (Copyright infringement occurs when material protected by copyright is used without consent.)

To avoid plagiarism, every writer should have a good understanding of the following:

What constitutes a copyright

How to apply the “fair use” doctrine

How to tell if a work resides in the public domain

How to get permission to use a copyrighted work

59@susvis

The Chicago Manual of Style’s guidelines for fair use

As a general rule, you should never quote more than a few paragraphs of text at a time or let quotations overshadow your own material.

Quotations or illustrations used should not be so long that they diminish the value of the copyright owner’s publication.

Proportion is more important than the actual length of material used; quoting 500 words of a 5000 word essay runs a much greater risk of infringement than quoting 500 words of a 50,000 word book.

Keep in mind that extensive paraphrasing is viewed as disguised copying. The paraphrasing of a small amount of material may not constitute copying at all while the paraphrasing of a large amount of material may require quoting or permission.

Any time you copy someone else’s materials, it is important to copy it accurately and to give credit to the original source.

60@susvis

Revising for Perfection

So much creative effort goes into writing the first draft of a document that all too often a writer – especially a beginning writer – assumes that when the first draft is finished, their work is done. They may make a few minor changes here and there and check for punctuation, typos, and spelling, but the idea of rewriting a large portion of the manuscript is inconceivable.

Unfortunately, first drafts are typically flawed in organization, quality, format, and language – not just in punctuation, typos, and spelling.

The purpose of a first draft is to get to the second draft; the purpose of the second draft is to get to the third draft, and so on until the final document is the best that it can possibly be.

61@susvis

How to revise

Fix the obvious problems before you start a page-by-page, beginning-to-end revision

Look at everything as an editor – not as an author: Treat your manuscript as if you were reviewing someone else’s work:

Does it draw you in and hold your attention?

Does it flow well?

Does it make one point after another on the same level, or does it seem to build toward a climax?

Is it a pleasure to read or do you feel like you can’t wait to get through it?

When you do a page-by-page revision (this should be one of your last revisions), work from a clean hard copy of the manuscript

62@susvis

The second and third draft

Locate and correct problems in each area:

Composition

• Passive voice, complex language, long sentences, non-specific terms, awkward style, non-parallel sentence structure, and missing transitions

Organization

• Unorganized material, missing headings and subheadings, blurring of facts and opinions, weak or missing closing

Wording and Phrasing

• Wordy phrases, unfamiliar words, clichés, jargon, and undefined acronyms, formal style, negative words, limited use of contractions

Formatting

• Bullets, lists, fonts, font characteristics (bold, italics, underlined), indentions, justification, table and figure captions, etc.

@susvis 63

“Kill your darlings.”

To be a good writer, you must be willing to strike out paragraphs and pages you gave birth to –some which might be quite good, and that you love – if they detract from, rather than strengthen the message you are trying to convey.

It isn’t just the bad stuff that gets taken out in a revision! Sometimes, good stuff has to be cut too.

When it comes to identifying large sections in a technical document that should be omitted, there are essentially three things should you look for:

Repetitions: Have you said the same thing multiple times?

Tangents: Did you adhere to your outline or does your document seem to go all over the place?

Unnecessary fillers: Have you padded your manuscript with unnecessary digressions, excessive description, or anything else that strikes you as filler?

64@susvis

The final draft – revising your prose

Locate and remove unnecessary words and phrases – especially unnecessary adjectives

Look for monotonous sentence rhythms: try to make your sentences vary in length

Locate and remove unnecessary adverbs and participles

– It’s usually a good idea to avoid adverbs completely

– If your writing does contain adverbs and participles, avoid placing them close together; because of the “ly” (adverb) and “ing” (participle) ending, too many adverbs/participles in a row draws the wrong attention to the text

Look for repetitious words or phrases

– Avoid using the same word twice in the same sentence or in sentences that are close together

– Avoid starting and ending sentences and paragraphs with the same word(s)

65@susvis

Final thoughts on revision

Attitude is important. If you review what you have written and think “This is awful!” you’ll only depress yourself. Your first draft is going to have problems –the revision stage is where you are going to fix those problems.

Although you are trying to create an excellent document through revision, don’t fall into the trap of constantly revising and never getting to “done”. No one is perfect, so don’t expect to produce a perfect document!

Likewise, don’t let the pressure of a deadline keep you performing this important step! If you do, the document you produce on time will most likely be inferior and require a significant amount of rework once your readers see it and begin making comments – causing great embarrassment to you.

66@susvis

Why getting feedback is important (and why many

people don’t ask for it)

Up until the time you solicit feedback, you are essentially working in a void. By seeking feedback, you are:

Inviting others to help you create a manuscript that will be both informative and a pleasure to read; and

You are taking positive, constructive steps to improve your own writing skills and develop as a writer.

Many people avoid asking others what they think about a piece of writing because they suspect the news will not be good. However, to know whether or not you are making yourself understood, constructive criticism from others will help.

The secret to dealing with criticism is to not take it personally! The criticism you receive is only criticism of the writing – not of you, the writer.

67@susvis

When to get feedback

Some stages where you might ask for feedback:

Outline

• Does the way I'm planning to present my ideas look appropriate?

• Does it look like I'm covering all the bases?

• Does it look like I’m presenting the information in the right order? (If not, Is there another way to order the information?)

• Does the reader need to know anything else up front?

• Do I have a clear main point?

• Have I created an interesting introduction and a strong conclusion?

@susvis 68

When to get feedback

First draft• Does the document make sense, and is it interesting?

• Is everything explained clearly?

• Have I given the reader enough information?

Early polished draft• Does the format of the document make it easy to understand?

• Are the transitions between my ideas smooth and effective?

• Do my sentences make sense individually?

• Do the graphics used clarify the text?

• Are there areas where additional graphics would help?

• How's my writing style?

Final draft• Are there any noticeable spelling, punctuation, or grammar errors?

• Is the final formatting ok?

• Does the document seem effective?

• Is there anything I should change before the document goes into publication?

After publication• What else might I have done to make this a stronger document?

• What should I do differently the next time I have to write a document?

• What can I learn as a writer from this writing experience?

@susvis 69

Who should you get feedback from?

The person who can offer the most effective feedback on your writing may vary depending on when you want the feedback and what kind of feedback you are looking for. Keep in mind, though, that if you are really concerned about a piece of writing, almost any thoughtful reader can provide useful information that will help you improve your writing skills.

A co-worker (a familiar and knowledgeable reader)

A Subject Matter Expert (a very expert reader)

Another writer, an editor, or a publisher (an expert in the art of writing)

Your spouse/roommate/friend/family member (an interested but not familiar reader)

70@susvis

You may be your best resource

Believe it or not, you can learn to be your own best reviewer, particularly if you learn to read your work with a critical eye. Here’s how:

Think about writing problems that you have had in the past. (Examine other things you have written for clues.) Do similar problems show up?

Give yourself some critical distance from your writing by setting it aside for a few hours, overnight, or even for a couple of days. Come back to it with a fresh eye, and you will be better able to offer yourself feedback.

Be conscious of what you are reading for. You may find that you have to read your draft several times—perhaps once for content, once for organization and transitions, and once for grammar and style.

71@susvis

What to do with the feedback you get

Don't be intimidated if a reviewer makes a lot of comments about your document. They may have had a lot to say because your ideas are interesting to them and they want to see you develop them to their fullest.

On the other hand, don't assume that your document is flawless if a reviewer did NOT provide many comments. Some reviewers have more to say than others, and sometimes one of your reviewers may just be too busy to spend a great deal of time writing comments.

Read ALL of the feedback that you get. Reviewer comments may expose one or more problem patterns in your writing that need to be addressed. They may also point out where you have confused, lost, or misled the reader. Both types of problems will need to be corrected before your document is published.

72@susvis

What to do with the feedback you get

Just because someone suggests you change something about your document doesn't mean that you have to do it.

Sometimes the person offering feedback may have misunderstood your intentions. Or maybe they made a suggestion that doesn't seem to make sense. Don't just follow every suggestion blindly. Talk about them with the reviewer, think about other options, and decide for yourself whether the advice you received was useful and should be followed.

Ultimately, the manuscript you submit for publication will be yours; therefore, you have the final say on its form and content. Take responsibility for being the final judge of what should and should not be done regarding each reviewer comment received.

73@susvis

A word about human nature and getting feedback

Usually, when we ask others for feedback, deep down, we’re hoping that the majority of the comments we get back will be positive and that only a few minor mistakes will be found. So, if lots of comments and suggestions come back, it’s only human nature to become frustrated and angry with the reviewer and to defend the writing style.

If you are angry or upset about a reviewer’s comments, set them aside for 24 hours. This gives you time to calm down and put things in perspective. Remember that the person who gave you the feedback did so because they genuinely wanted to provide you with information that would help you produce a better document.

After, taking a day off, go back and to read through the reviewer's comments again and think about how to best address them. Take the time to reread your own writing and evaluate it more critically yourself. If necessary, follow up with the reviewer for additional feedback once your anger has passed.

74@susvis

Promote yourself and what you produce

Tweet about events that you are taking part in, published items that you worked on, or simply information that would be interesting to your followers.

Using Tweetdeck, you can monitor all the social streams you care about and in one easy step, add a point of view while you retweet a message, and schedule it to appear 5 hours from now.

On LinkedIn, update your status by sharing links to interesting articles, blogs, websites or video that are related to your area of expertise.

Contribute to the right LinkedIn groups to maximize your reach. Join the conversation taking place in active discussions.

75@susvis

Why Should I Use Social Media?

1. Connect with existing customers

2. Get feedback from customers

3. Spread ideas

4. Watch competition

5. Amplify messages to wider audiences

76@susvisBe Seen as the Expert You Are!

Mindset Change is Required

77@susvis

Current Mindsets Future Mindsets

I am valued for the knowledge I have

Social means I’m on LinkedIn

Social tools are yet another thing to do

I worry about the risk of sharing too much

I am valued for the expertise I share

Social is collaborating across networks to solve problems

Social business is embedded into the way we work

I am trusted and feel prepared to share appropriately

About Roger E. Sanders

@susvis 78

Roger is a well established and published technical author,

who has been writing professionally for 13+ years. He has

authored 20 books, several white papers, numerous

magazine articles, on-line tutorials, blogs, reference material,

training material, and IBM certification exams.

Roger is best known for his certification guides that he

published through MC Press.

See more about Roger on his LinkedIN profile.

About Susan Visser

I’m a career IBMer and have had

jobs related to writing my entire

career. I’ve written two books and

helped with hundreds more. I’ve

been blogging for more than 10

years and now spend a good

portion of my time doing social

coaching.

• Connect to me:

• Twitter

• LinkedIN

• Blog

• Slideshare

• Tumblr

• Google+

@susvis 79

Read More!

• 15 Reasons I Think You Should

Blog by JOSHUA BECKER

• Writing Research Papers by

Aaron Hertzmann

• Soft skills are sexy by Jennifer

Kavur

• Advice on Academic Writing

• How to Blog When You're Not

in the Mood to Write by Rebecca

Livermore

• Blogging for DBAs by Ember

Crooks

@susvis 80

Summary

1. Schedule time to write.

2. Have a strong outline before you start to write. Tell a story: Have a beginning, say a problem that needs to be solved; a middle, the search for a solution; and an end, a strong conclusion.

3. Let some personality show through in the writing. The last thing you want to do is to bore the reader so that the ending is never reached.

4. Don’t plagiarize.

5. Diagrams and tables are useful, but ONLY if they are tied tightly with the text.

6. No one’s writing is perfect… every author needs to review and revise their work many times.

7. To make revision as easy as possible, look for one specific thing at a time each time you go through your draft.

8. For everyone, but especially if you are English-second language, consider reading the text out loud or have the computer read it to you.

@susvis 81

The End.

See you on Twitter & LinkedIn!

@susvis