# Welcome to SMIRK Unit
6 - Technical writing

- What is it?
- The purpose of your writing
- Top tips
- Organisation
- The introduction
- The literature review
- Style
- Contractions and personification
- Gender-neutral language
- Plain English
- Which voice?
- Back to main index

######
SMIRK - Technical writing by Vince Ricci: CIEE, Joe Schall: Penn State University, Glynis Perkin: Loughborough University modified by Marion Kelt, GCU is licensed under a Creative Commons Attribution 4.0 International License.
Based on a work at http://www.slideshare.net/tokyovince/introduction-to-technical-writing-4305074 http://www.slideshare.net/engCETL/technical-report-writing-handout https://www.e-education.psu.edu/styleforstudents/c1_p15.html.

# What is it?

These pages contains general tips and hints for writing articles and longer pieces. We also have specific guidance on report writing. Technical writing is informative writing that relates to the following subject areas:

- technical
- scientific
- engineering

It conveys complex information to a specific audience. If the audience cannot understand or use the information presented, then the writer has failed. Good technical writing is:

- accurate
- clear
- concise

Accuracy. Avoid writing a phrase like “Increasing the temperature caused a large change in the reaction rate.” Instead, write “Increasing the temperature by 10°C doubled the reaction rate.”
Clarity. If a report does not contain clear information, the reader cannot understand, believe, or care. Three questions to ask yourself:

- Do I understand?
- Do I believe?
- Do I care?

Conciseness. end result result , future plans plans.

####

######
SMIRK - Technical writing by Vince Ricci: CIEE, Joe Schall: Penn State University, Glynis Perkin: Loughborough University modified by Marion Kelt, GCU is licensed under a Creative Commons Attribution 4.0 International License.
Based on a work at http://www.slideshare.net/tokyovince/introduction-to-technical-writing-4305074 http://www.slideshare.net/engCETL/technical-report-writing-handout https://www.e-education.psu.edu/styleforstudents/c1_p15.html.

# The purpose of your
writing

Technical writing should be goal-oriented. It should convey information clearly and include no extraneous material. It should help the reader to find essential information and have a specific format which allows the reader to quickly locate everything in an organised fashion. You should consider:

- purpose of document
- intended audience
- context

If the audience cannot use, apply or understand the information presented - then the author has failed
Purpose. What is the ultimate goal? This should be practical, the purpose determines the format of your paper. Usually:

1. Title
2. Abstract
3. Introduction
4. Body
5. Results
6. Discussion
7. Conclusion
8. Acknowledgments
9. References

####

######
SMIRK - Technical writing by Vince Ricci: CIEE, Joe Schall: Penn State University, Glynis Perkin: Loughborough University modified by Marion Kelt, GCU is licensed under a Creative Commons Attribution 4.0 International License.
Based on a work at http://www.slideshare.net/tokyovince/introduction-to-technical-writing-4305074 http://www.slideshare.net/engCETL/technical-report-writing-handout https://www.e-education.psu.edu/styleforstudents/c1_p15.html.

# Top tips

Audience: You should tailor your communication to meet the audience needs. Ask yourself who are your intended readers? You should use different language when addressing a technical expert than to an audience that has limited knowledge. Think about what the audience members will do with the information. Consider their knowledge level.
Context: The context determines how the reader or listener will receive and interpret the message. It helps the writer determine what format is appropriate and how the subject should be approached.

#### Some more top tips for writing your paper

Organisation: Identify the one central and novel contribution of your paper. Write this down in one paragraph. As with all your writing, this must be concrete. A contribution includes an addition to your field’s overall knowledge
How do you add value? Don’t write “I analyzed data on executive compensation and found many interesting results.” Explain the central results. For example, Fama and French (1992) start their abstract with:
“Two easily measured variables, size and book-to-market equity, combine to capture the cross-sectional variation in average stock returns associated with market B, size, leverage, book-to-market equity, and earnings-price ratios.”
Distilling one central contribution will take some thought. Focus on one contribution, and help readers to get it quickly. Your readers are busy and impatient. Never assume that they will read the whole paper from start to finish. Make it easy for your readers to skim. Readers want to know your basic result.

######
SMIRK - Technical writing by Vince Ricci: CIEE, Joe Schall: Penn State University, Glynis Perkin: Loughborough University modified by Marion Kelt, GCU is licensed under a Creative Commons Attribution 4.0 International License.
Based on a work at http://www.slideshare.net/tokyovince/introduction-to-technical-writing-4305074 http://www.slideshare.net/engCETL/technical-report-writing-handout https://www.e-education.psu.edu/styleforstudents/c1_p15.html.

# Organisation

Organize the paper in “triangular” or “newspaper” style, not in “joke” or “novel” style. Newspapers start with the most important part, then fill in background later for readers who want more details.

A good joke or a mystery novel has a long windup to the final punchline. Put the punchline right up front and then slowly explain the joke. Too often, the reader never really finds out what the contribution of the paper is until the last page, the last table, and the last 5 minutes. They don’t care how you came to figure out the right answer.
Put your contribution (what), before methods (why or how). Readers skim, so use the triangular style and open with your punchline.
Your Abstract
Most journals allow 100-150 words. The main function of the abstract is to communicate your contribtuion. Do not mention other literature in the abstract. It must be concrete. Say what you find, not what you look for. Don’t write “data are analyzed, theorems are proved, discussion is made.”

####

######
SMIRK - Technical writing by Vince Ricci: CIEE, Joe Schall: Penn State University, Glynis Perkin: Loughborough University modified by Marion Kelt, GCU is licensed under a Creative Commons Attribution 4.0 International License.
Based on a work at http://www.slideshare.net/tokyovince/introduction-to-technical-writing-4305074 http://www.slideshare.net/engCETL/technical-report-writing-handout https://www.e-education.psu.edu/styleforstudents/c1_p15.html.

# The introduction

Your Introduction
The introduction should start with what you do in this paper, the major contribution. Don’t just state your conclusion “My results show that the pecking-order theory is rejected.” Give the facts behind that result.
“In a regression of x on y, controlling for z, the coefficient is q.” The first sentence is the hardest.
“Two easily measured variables, size and book-to-market equity, combine to capture the cross-sectional variation in average stock returns associated with market B, size, leverage, book-to-market equity, and earnings-price ratios.”
Do not start with philosophy: “Financial economists have long wondered if markets are efficient.”
Do not start with “The finance literature has long been interested in x.” Start with your central contribution:
“Two easily measured variables, size and book-to-market equity, combine to capture the cross-sectional variation in average stock returns associated with market B, size, leverage, book-to-market equity, and earnings-price ratios.”
Three pages is a good upper limit for the introduction. Remember:

- Abstract - no literature review
- Introduction - first sentence
- Start with contribution

####

######
SMIRK - Technical writing by Vince Ricci: CIEE, Joe Schall: Penn State University, Glynis Perkin: Loughborough University modified by Marion Kelt, GCU is licensed under a Creative Commons Attribution 4.0 International License.
Based on a work at http://www.slideshare.net/tokyovince/introduction-to-technical-writing-4305074 http://www.slideshare.net/engCETL/technical-report-writing-handout https://www.e-education.psu.edu/styleforstudents/c1_p15.html.

# The literature review

First, your readers are most interested in figuring out what you do. After you’ve explained your contribution, then you can write a brief literature review. Make it a separate section. Be generous in your citations. Set your paper off against two or three closest current papers, and give proper credit to people who deserve priority for things that might otherwise seem new.

The body of your paper
Your task now is to get to the central result as fast as possible. Most papers start with:

- long motivation
- long literature review
- big complex model
- descriptive statistics
- preliminary results
- side discussions

Boring! Put nothing before the main result that the reader does not need to know in order to understand it.

Your conclusions
Do not restate all of your findings. One statement in the abstract, one in the introduction and once more in the body of the text should be enough. You can include a short paragraph or two acknowledging limitations, and suggesting implications beyond those in the paper. Keep it short. Don’t speculate.

Remember:

- Literature review – meaningless before your contribution
- Body of the paper – all about your main result
- Short conclusion

####

######
SMIRK - Technical writing by Vince Ricci: CIEE, Joe Schall: Penn State University, Glynis Perkin: Loughborough University modified by Marion Kelt, GCU is licensed under a Creative Commons Attribution 4.0 International License.
Based on a work at http://www.slideshare.net/tokyovince/introduction-to-technical-writing-4305074 http://www.slideshare.net/engCETL/technical-report-writing-handout https://www.e-education.psu.edu/styleforstudents/c1_p15.html.

# Style

Keep the paper as short as possible. Every word must count. As you edit, ask yourself “Can I make the same point in less space?” and “Do I really have to say this?” Don’t repeat. If you’ve said it once, you don’t have to say it again.

Strive for precision
Document your work. A fellow graduate student must be able to sit down with your paper and reproduce every number in it from the instructions given, including any print or web appendices. Don't repeat! Remember:

- Be precise
- Document your work
- Simple is best

Writing tips
The most important thing in writing is to keep track of what your reader knows and doesn’t know. Think about who are your intended readers? Consider their knowledge level. Keep in mind what you have explained and what you have not. Don't make assumptions.
There is a move towards using active verbs, not passive, in journals and technical literature. There are no hard and fast rules on this, and the issue is discussed later in this section. For example: “it is assumed that x = 3” becomes "we assume that x=3". Search for “is” and “are” in the document to identify every passive sentence. Take responsibility for what you are writing. Remember:

- Audience is king
- Assume nothing
- Check whether active or passive verbs are specified
- Take responsibility

Use normal sentence structure: subject, verb, object. Not “The insurance mechanisms that agents utilize to smooth consumption in the face of transitory earnings fluctuations are diverse” Instead “People use a variety of insurance mechanisms to smooth consumption.” Avoid technical jargon wherever possible. Remember:

- Present tense (be consistent)
- Subject, verb, object
- Limit jargon (if possible)
- Concrete examples

Be a writer! Research papers are essays. Spend at least 50% of any project on writing. Pay attention to the writing in papers you read. Notice the style adopted by authors you admire. Most of all, learn to write. How? Read everything and write anything.

####

######
SMIRK - Technical writing by Vince Ricci: CIEE, Joe Schall: Penn State University, Glynis Perkin: Loughborough University modified by Marion Kelt, GCU is licensed under a Creative Commons Attribution 4.0 International License.
Based on a work at http://www.slideshare.net/tokyovince/introduction-to-technical-writing-4305074 http://www.slideshare.net/engCETL/technical-report-writing-handout https://www.e-education.psu.edu/styleforstudents/c1_p15.html.

# Contractions and
personification

Eliminating contractions and using apostrophes
Contractions, where an apostrophe is used to contract two words into one by joining parts of them, should not be used. Only use them if you are quoting something that contains them. If you avoid contractions, you will discover that your writing becomes more emphatic and leans toward the active voice. Remember: in technical writing, apostrophes contracting two words (such as, “it’s,” “they’ve,” “who’s”) signal that the two words can and should be written out separately. For instance, haven’t should be written as have not, it’s should be written as it is, which will also help you to avoid incorrect usage of its and it's.

Take care with the use of apostrophes demonstrating possession. For example:

> Professor Blagg has had two years of experience in dealing with his student’s difficulties.

In the above sentence, student’s implies that the Professor has only dealt with the difficulties of one student. Whereas students’ would imply that he has dealt with the difficulties of more than one student.

The correct usage of it's and its is as follows: It's unfortunate that the laboratory had its computers stolen last night.

Curbing feelings and personification
Use of the word “feelings” or the verb “feel” in technical writing often leads the writer into trouble. “Feel” has emotional connotations, and feelings are not a relevant part of rational conclusions in your writing. Also, use of the term can lend the appearance of uncertainty, especially when applied to quantities or conclusions, for example:

- I feel that the best answer is 3.2”
- “we feel that this conclusion is correct”

You should also avoid unintentional personification - assigning human traits to inanimate objects. A sentence such as “Boeing stock enjoyed a 2% increase today” could imply that stocks have emotions. Although such a sentence may appear in a newspaper, its tone would not suit a technical paper.

####

######
SMIRK - Technical writing by Vince Ricci: CIEE, Joe Schall: Penn State University, Glynis Perkin: Loughborough University modified by Marion Kelt, GCU is licensed under a Creative Commons Attribution 4.0 International License.
Based on a work at http://www.slideshare.net/tokyovince/introduction-to-technical-writing-4305074 http://www.slideshare.net/engCETL/technical-report-writing-handout https://www.e-education.psu.edu/styleforstudents/c1_p15.html.

# Gender-neutral language

Most students are aware of this issue, but if they just use “his/her” repeatedly then they are not making their writing highly readable. Also, writing a sentence such as “Someone should lend their voice to this problem” is still grammatically unacceptable because “someone” is singular and “their” is plural. Here's how to attack the problem:

- be more specific or creative about word choice (writing “humans” rather than “man”).
- use plural nouns rather than singular ones when appropriate (“scientists” rather than “a scientist”), or by avoiding gender-specific pronouns (“the author” rather than “he”).
- write “he or she” (not “he/she”) when it is not awkward or overly repetitive to do so.
- change some words to other parts of speech, thereby avoiding gender-specific pronouns (“walking” might work better than “he walked” as long as the grammar of the revision is sound).
- alternate between using “he” and “she”, especially in longer pieces.

With these tactics in mind, look at the following example:

> The consumer himself has the power to reduce fuel costs: If he sets his residential thermostat 2 degrees higher in the summer and 2 degrees lower in the winter, he saves energy.

In a revised version of this sentence, the gender-specific language of the original is avoided:

> Consumers have the power to reduce fuel costs: By setting their residential thermostats 2 degrees higher in the summer and 2 degrees lower in the winter, they save energy.

Standard English usage is that the masculine form (“he” or “his”) refers to either gender in writing, but only rely on this when you have to. However, don't go too far - like “personhole cover” “personkind” “s/he”; instead, exercise your options as a writer wisely.

####

######
SMIRK - Technical writing by Vince Ricci: CIEE, Joe Schall: Penn State University, Glynis Perkin: Loughborough University modified by Marion Kelt, GCU is licensed under a Creative Commons Attribution 4.0 International License.
Based on a work at http://www.slideshare.net/tokyovince/introduction-to-technical-writing-4305074 http://www.slideshare.net/engCETL/technical-report-writing-handout https://www.e-education.psu.edu/styleforstudents/c1_p15.html.

# Plain English

Jargon, especially that which has grown out of computer usage, may enrich our language. But using “debug,” and “flame” may not be accpetable in formal writing, so you must understand how to recognise it and when it is unacceptable. Issues range from:

- redundancy: “red in colour”, "and also"
- overly formal wordiness: using “at this point in time” rather than “currently”
- specialised technical slang: using “aeroplane rule” to describe the concept that greater complexity increases the likelihood of failure

When it takes the form of redundancy and wordiness, simple editing is critical. When jargon becomes specialised slang, we must consider audience and context to decide on how much is appropriate. A group of web designers might know that “angry fruit salad” refers to visual design that includes too many colours, but a general audience would not. Your writing should include the technical words that are associated with your subject and it must read as if it has been written by an educated person. Nevertheless, if your readers need to use a dictionary frequently, then they are likely to stop reading.

Always use the following plain English principles when writing:

- Always choose the simpler wording or word (for example, “today” rather than “in today’s modern society”; “sandy” rather than “arenaceous”).
- When you feel jargon is necessary, explicitly define the terms you use, or define terms by creating context for them in the sentence.
- Use technical slang in moderation, in presentations, in conversation with peers, in interviews, in e-mails and memos, and in cover letters, but only when your audience is certain to understand your meaning.
- remember this is a serious piece of academic writing, so use good English and don't introduce humorous anecdotes.

####

######
SMIRK - Technical writing by Vince Ricci: CIEE, Joe Schall: Penn State University, Glynis Perkin: Loughborough University modified by Marion Kelt, GCU is licensed under a Creative Commons Attribution 4.0 International License.
Based on a work at http://www.slideshare.net/tokyovince/introduction-to-technical-writing-4305074 http://www.slideshare.net/engCETL/technical-report-writing-handout https://www.e-education.psu.edu/styleforstudents/c1_p15.html.

# Which voice?

Using the third person
The traditional practice in technical writing is to use the third person. This means that you would not write, ‘I have verified that all the results are included in the report’. Instead you would write, ‘It has been verified that all the results are included in the report’.
‘We will show that the experiment has produced some interesting results’ should be written, 'It will be shown that the experiment hasproduced some interesting results’.
This can sound contrived and pompous; but it is the accepted style of writing in academia. However, the situation in the workplace and in technical journals is changing and there are now no hard and fast rules. It is important that you find out what rules or guidelines (if any) are available for your work. These can be either on GCULearn or in the instructions for authors section of a journal's web site.

Which "voice"?
As well as using the third person you may write in the active or passive voice. This provides opportunity for you to place emphasis on the appropriate part of the sentence as shown here:

- Passive: The first steam locomotive was designed by George Stephenson. Here the emphasis is on the first steam locomotive (the result or a fact).
- Active: George Stephenson designed the first steam locomotive. Here the emphasis is on George Stephenson (the person or thing who did it).
- Passive: The accuracy of measurements has been improved by new laboratory equipment.
- Active: New laboratory equipment has improved the accuracy of measurements.

Again, there are so hard and fast rules, so check before submitting your work. This is the end of our section on technical writing.

####

######
SMIRK - Technical writing by Vince Ricci: CIEE, Joe Schall: Penn State University, Glynis Perkin: Loughborough University modified by Marion Kelt, GCU is licensed under a Creative Commons Attribution 4.0 International License.
Based on a work at http://www.slideshare.net/tokyovince/introduction-to-technical-writing-4305074 http://www.slideshare.net/engCETL/technical-report-writing-handout https://www.e-education.psu.edu/styleforstudents/c1_p15.html.