Technical Writing Style Research

7/30/2019 Technical Writing Style Research

http://slidepdf.com/reader/full/technical-writing-style-research 1/13

MEMORANDUM

TO: DR. DANIEL JONES

FROM: JONATHAN HAUPT ( JLH )

SUBJECT: PROPOSAL FOR STYLE PROJECT

DATE: MARCH 19, 2013

INTRODUCTION

I choose my project topic “On a Professional Discourse Community” because I felt it would provide the

most practical benefit to my education. Analyzing professional documents using principles that I have

learned in this class provided me with a “hands-on” application of what I have learned. I would learn

how writing is actually applied in the workplace, along with any challenges that the members of the

discourse community face in communicating.

I choose to investigate the “satellite technology instructors” community because my father is a satellite

communications instructor for a military base in Okinawa, Japan. Using him as a resource, I drew on a

wealth of communication examples for my project, and, through conversations with him, learn from

first-hand account about the challenges he faces. The ease of access to that information, as well as the

variety of quality documents I could include, allowed me to make a comprehensive analysis on a range

of communication formats.

Readers of my project should learn the value of being aware of the range of tools a technical writer can

employ to effectively communicate to his or her target audience, even within highly technical discourse

communities.

OVERVIEW OF STYLE PROJECT

I choose to focus my project on satellite technology instructors, specifically civilian contractors working

with the military. This focus has value for several reasons.

Firstly, it deals with highly technical diction. It is important to understand that the use of advanced

terms is necessary in many discourse communities. The book addresses this reality: “Technical terms

are the currency of information in trades, professions, hobbies, and the sciences… These terms and

countless others save *professionals+ incalculable time and effort” (119). The trick is to balance the need

to use these terms with the comprehension level of your audience. Our text notes, “Too much technical

prose fails to be effective because it completely or even partially ignores the audience” (37). Satellitetechnology instructors actively bridge the knowledge gap between learned professionals and learning

pre-professionals.

Secondly, the topic was unique in that these instructors possess a unique position, whereby they write

professionally on advanced telecommunication concepts, directly communicate that information with

students, develop manuals and usage procedures for other professionals, and daily interact with military



2 | P a g e

personnel who have a different background than they do. Analyzing discourse from their perspective

afforded insight into the most important principles of technical writing.

The most difficult aspect of this assignment was determining the subject of my analysis for each

document. Many times I felt like I was being redundant in addressing points that were the same or very

similar. This made it difficult to write for some of the sources. Often, what I would do to rectify that

situation was to have a conversation with a professional in the field, my father. I found that because I

could connect with him, and just listen to what he was concerned about, I could reflect his problems

into my analysis.

CONCLUSION

This project has taught me a great deal about how highly technical, professional documents are written

the way they are, and the advantages that these practices provide. Studying how their documents

addressed the needs of their students, other professionals, or superiors, allowed me to gain lessons on

effective technical writing in any discourse community.

I think students would get a great deal more out of this assignment if they actually connected with a

professional in the discourse community they are focusing on. This could be encouraged in the project

assignment. Methods to go about the connection could be forums, or social media (Twitter). While this

concept may not be practical in most cases, in my personal experience, this method rewarded me

considerably.



3 | P a g e

Samples from aProfessional Discourse

Community

Jonathan Haupt



4 | P a g e

Sample 1:

United States Marine Corps, Communication Training Center, Marine Corps Communication Electronics

School, Training Command. “SW.04.01 Presentation Mar 10 2010.ppt” Page 6. Microsoft

PowerPoint.

Intended Audience: Marines studying satellite technology

A fundamental part of being a satellite instructor is, naturally, instructing a class. Often, these

classes are taken by groups of people, such as marines, who have some kind of background in the field.

However, due to the highly technical nature of the field, complex concepts may be difficult to express

using words alone. Graphics and other visual aids can be helpful, especially when dealing with

electronics. The above example effectively illustrates a particulate piece of highly technical equipment.

The terms for aspects of the equipment are connected to the graphic with red arrows.

The compilation is simple, yet elegant in its effectiveness and brevity. The audience is

encouraged to fit the pieces of the puzzle together, which engages them in the learning process. Our

book supports the use of this method. One of the “Tips for Using Clear Technical Language” is: “Provide

a graphic to show what the object or concept is” (134). A primary goal of effective satellite technology

instructors is to use any tools that improve the quality of instruction. Use of this graphic is one example

that demonstrates the pursuit of that goal.

NMP Transit Case

1. NMP Input / Output Pane

2. Linkway Satellite Modem

3. Linkway Satellite Modem

4. Keyboard Video Mouse



5 | P a g e

Sample 2:

Spectrum Office. "Volume 3, Edition 1 (Jan - Mar 2013). Quarterly Spectrum Newsletter . n.p., n.d. Web.

13 March 2013

Intended audience: III Marine Expeditionary Force in Okinawa, Japan

The above table is a schedule of events that relate telecommunications technology, as part of a

larger excerpt from a newsletter distributed to personnel. Satellite communications instructors are

often contracted by the Department of Defense, and this professional relationship opens up larger

educational and professional opportunities on a national scale. The forums and workshops are examples

of some of these opportunities. Instructors of the technology that these events will focus on have an

obligation to connect their students the events. The challenge is in distributing information about these

opportunities, and connecting their students to the greater possibilities that are available to them.

This schedule arranges that information in a way that is identifiable for the reader. Appropriate

information is provided in a logical and concise format. This is done so readers can reference that

information quickly, and use it to their advantage.

Event Dates Location

WestPac Innovation Forum 17 Jan 2013 Butler O’Club, Plaza Housing

Spectrum Apprentice Class 1 8 Jan – 17 Apr 2013 Kessler AFB, Biloxi MI

Spectrum Apprentice Class 2 18 Apr – 26 Jul 2013 Kessler AFB, Biloxi MI

DoD Spectrum Workshop 25 Feb – 1 Mar 2013 (Tentative) Washington D.C.

Navy and MC Spectrum Conf TBD San Diego, CA



6 | P a g e

Sample 3:

INTRODUCTION (4 Min)

(ON SLIDE # 1)

1. GAIN ATTENTION

Has anyone bought a car before? If you have, then you know you research the

vehicles you’re interested in, the price you can afford, test drive the

vehicle, and finally check which options you can get. In satellite

communications, you have to know the satellites you are going to use and the

capabilities of the terminal the operator will use. During this period of

instruction, you the students will learn the basic fundamentals of satellite

communications.

(ON SLIDE # 2)

2. OVERVIEW. Good morning/afternoon, my name is _______________. The purpose of this lesson is to

provide you with a basic understanding of satellite fundamentals. I will do this by discussing an overview of

satellite communications, the space segment, satellite types, the control segment, and the ground segment. This

class directly relates to the rest of the Support Wide Area Network (SWAN) RF course you will be receiving.


School, Training Command. Lesson Plan: Satellite Fundamentals.

Intended Audience: Satellite technology instructors

This example is from a lesson plan created by satellite tech instructors, for satellite tech

instructors. The purpose of the document is to provide the instructors with a framework that they can

use to base their lecture upon. The document addresses several needs, which can be seen in the

example section. The first would be adaptability. The instructors can create their own lesson, with anadded touch of personality, from the general examples given in the lesson plan. Also, multiple

instructors could use this document, because it is not created for one specific instructor, but rather any

number of instructors who could teach the class. Finally, the lesson plan creates a procedure for the

instructor to follow, with the slide progression notes, instructor note, and titles for each section of

material.

INSTRUCTOR NOTE:

This is a lesson purpose class and has no Terminal Learning Objectives (TLO) or Enabling

Learning Objectives (ELO).



7 | P a g e

Sample 4:

If you suspect you are the victim of an attack (you opened an attachment or clicked on a link)

· Shutdown your system immediately and remove it from the network

· Contact Tech Support for resolution

· Contact the NOC to report the incident

Your quick response can make the difference between a minor incident and a major data breach.

n.a. “Security Awareness Reminder - TCS Phishing Attempts on the Rise.” TCS Employees. 9 Feb. 2013.

Intended Audience: TCS Employees

Sample 4 effectively demonstrates the importance in the verb style in professional discourse.

The above selection is an excerpt from an email sent to employees of a telecommunications company.

The email is in response to a recent rise in security breaches, which can cause valuable information to be

compromised. The email is a call to action for the employees, and it uses the verb style, which is “a style

based on verbs, on action” (49). Appropriately, the employees are given a methodology to respond to

these threats. Use of the verb style here highlights the importance of taking these steps by making use

of action verbs to create directions that are clear, brief, and effective.



8 | P a g e

Sample 5:

Gentlemen,

Current Transmission Plan for our SWAN/VSATs is attached. Carrier 215.

Semper Fidelis,

(NAME WITHELD)

n.a. " FW: SWAN Ku-Bandwidth Request / CTC-3 Carrier (UNCLASSIFIED)."Message to all marines in the

CTC, Okinawa, Japan. 3 December 2013. E-mail.

Intended Audience: III Marine Expeditionary Force in Okinawa, Japan

This e-mail exemplifies the nature of professional communication between civilian satellite

technology instructors and their military counterparts. As the text explains, “Styles are shaped in large

part by the discourse communities in which and for which documents are written” (22). Understanding

the environment in which we communicate is critical when inter-professional communication is taking

place. In this case, language customs in the Marine Corps include directly stating the information, and

the use of professional acronyms such as “SWAN/VSAT”. A formal, spare tone is adopted, withrespectful nods to their organization with “Semper Fidelis”, the motto of the marines. Knowledge of

these factors, with appropriate application of the language customs, allows the civilian instructor to

communicate most effectively with the marines.



9 | P a g e

Sample 6:

g. Cisco 3560 Catalyst Switch. The Ethernet switch on an NMP is the layer 2 aggregation point

for the NMP. The MRT, AMRT, NMS Laptop, NCC, and ANCC all communicate via the switch.

There are 24 fast Ethernet ports and 2 Small Form-factor Pluggable (SFP) slots.


School, Training Command. “Student Handout: Network Management Package (NMP)

Equipment Controls and Indicators”. Page 5.

Intended Audience: Satellite technology students, marines

Sample 6 is a selection from a student handout, given to marines who are well into theireducation in satellite technology. As such, the sample includes highly technical diction. Use of terms

such as “NMP” and “aggregation point” is common in the text, which requires a great deal of knowledge

about the subject area. Use of these terms, when appropriate, is not a problem in itself. The book

supports the use of technical terms, contingent upon the audience of the writing. “The level of

technically of a subject is often in direct proportion to the audience’s familiarity with the subject…*The+

level of technicality can be difficult to establish clearly and objectively for all audiences” (34). While the

terms are not appropriate for all audiences, the terms can be considered appropriate if their use

matches with the audience’s technical knowledge.

The challenge that instructors face is balancing the need to include appropriate technical terms,

which are necessary tools for professionals in the field, and the need to explain those terms to their

students. Instructors must introduce a term first, before they apply it. Once those terms are absorbed

by the students, they can be used to help explain other terms that relate to the technology. The above

sample uses these complex terms, which the students should already know, to explain what the “Cisco

3560 Catalyst Switch” is. The relationship between the quality of instruction and the technicality of the

subject is such that instructors need to be fully competent in the use of these terms, as well as their

students understanding , or lack thereof.



10 | P a g e

Sample 7:


School, Training Command. “SW.04.02 Presentation Mar 10 2010.ppt” Page 2. Microsoft

PowerPoint.

Intended Audience: Marines studying satellite technology

“There is a common problem, in that some abbreviations have more than 1 common meaning. When

that occurs the instructor has to state what the correct meaning of that term is for the class. If the

instructor states it wrong, then that is what the students go by anyway. So the onus is on the instructor

to get it right.” – Quote from Howard Haupt, a satellite technology instructor

This issue is one that might not be directly obvious to an outsider, but was indicated to me by a

professional in the field as a problem that instructors like himself have to be aware of. The problem lies

in the use of many abbreviations for technical terms. These abbreviations are arguably necessary to the

field, as they noticeably shorten commonly used phrases into smaller packages that can be read andspoken much more quickly. This is a tool that is used by professionals in all technical fields to improve

their communications with similarly educated professionals.

The problem that develops (even with these educated professionals) is when commonly used

acronyms overlap. The above sample indicates a situation where such confusion could take place. Short,

3 letter acronyms, as well as extensions with numbers and other identifiers (such as “Mk.” and “V.”)

create a host of concerns. There a myriad of various acronyms, many of which are very similar. Satellite

technology instructors have to be careful using these tools, or they may provide confusing or conflicting

information to their students.

• NMP Installation with a SWAN-D-V1/V2

• NMP Installation with a SWAN-D-V3

• NCC / NMS Start-Up Procedures

• NCC / NMS Shut-Down Procedures

• NMP Teardown

• NMP Theory of Operation



11 | P a g e

Sample 8:

A. CURRENT POSITION RESPONSIBILITIES AND ACCOMPLISHMENTS

Briefly describe the major/primary responsibilities of your current position. Discuss your

performance relating to these responsibilities, including important job-related accomplishments

that you have achieved during the review period. Relate these accomplishments to any previously

established objectives.

I am WPPL/VSAT instructor at CTC-3 in Okinawa. My job involves planning and conducting training on

these systems here at CTC-3 and at other local units as required. My job also involves updating training

material to keep them current. During this past year I have taught all assigned classes, as well as a

couple of one-time only classes I taught on the MRC-142. This year I attended a couple of CCNA classes

to broaden my Network background.

Haupt, Howard. “TeleCommunication Systems Human Resources”. Self-Evaluation. 2012.

Intended Audience: TCS employee supervisor

Most professionals have a boss they report to, or a supervisor that works for the company that

hired the professional. This document exemplifies an aspect of the employee/supervisor relationship.

The writing in Sample 8 demonstrates a professional tone, it is noticeably free of errors, and it quickly

responds to the question in a manner that is free from clutter and filler text. Additionally, the evaluation

does contain a few technical terms, but it is largely written in plain English.

This is, according to the text, “the dominate style in technical prose”. Use of this style allows

writers to “write in this simple, no-nonsense style, a style also called a reader-friendly style” (52). Evenin highly technical professional communities, the value of the plain style is not forgotten. Use of this

style is always a safe bet in technical writing.



12 | P a g e

Sample 9:

If multiple Linkway modems are to be used at the hub:

Select only the file with “HHH” in the file name (this file will configure the G0/0 subinterfaces for the

802dot1q trunk to the Linkway switch and make the required changes for RIPv2).

Right click and select Send To > EditPad Lite

Select File > Save As on each individual file.

Manually change the HHH in the suggested filename to the Hub system number.

Find and replace the following on All Open Documents

Find: HHH and replace with: Hub system number.

Save and close the file.

Repeat the Save As/Close steps if a 2nd hub is being configured.


School, Training Command. “How to use Configuration Templates_SWAN DMVPN_v2.doc” Page

3.

Intended Audience: SWAN system users

Sample 9 is a selection from a reference guide to use “configuration templates”. These would be

used by someone who is familiar with the technology, but might need to use this guide for a quick

reminder about the details of its application. Writing and maintaining guides like these is part of being a

professional in the field. This is because professionals are not always using every technology they are

familiar with, and when they are called to work with these technologies, it is logical that procedures of

operation should be available to them.

Knowing the audience (and their knowledge level), we can say that the use of technical

terminology in the procedures is surprisingly limited. The sample above follows a logical path, and while

the lay person might not be familiar with every term, anyone who is reasonably comfortable with a

computer can recognize and accomplish many of the steps. This manual exhibits a user-friendly style

(based on the intended audience). The manual assumes you have background knowledge about the

subject, but have completely forgotten all the methods of its operation. Thus, it avoids using many of

the shortcut jargon, and limits itself to basic diction within the discourse community. The book stresses

this concept of limiting the use of jargon: “If even one member of the audience is confused by the terms

you use, then you are not achieving your purpose as effectively as you should” (129).



13 | P a g e

Sample 10:

Global variables used in the templates:

RR1 Remote site 1 SWAN # & Class C block RR2 Remote site 2 SWAN # & Class C block RR3 Remote site 3 SWAN # & Class C block

HHH Hub site SWAN # & Class C block

AAN.BBN. NIPR Class A & B block

AAS.BBS. SIPR Class A & B block

<N-EIGRP-ASN> = NIPR EIGRP ASN number <N-CCM-GW-IP> = IP address of router on VLAN 22 for CCM GW

<N-CCM-PRI-IP> = IP address of Primary CCM (Subsriber)

<N-CCM-SEC-IP> = IP address of Secondary CCM (Publisher)<N-TFTP-SERVER-IP> = IP address of TFTP Server (Publisher)<N-DHCP-SERVER-IP> = IP address of DHCP Server (Publisher)

<S-EIGRP-ASN> = SIPR EIGRP ASN number <S-CCM-GW-IP> = IP address of router on VLAN 22 for CCM GW

<S-CCM-PRI-IP> = IP address of Primary CCM (Subsriber)

<S-CCM-SEC-IP> = IP address of Secondary CCM (Publisher)<S-TFTP-SERVER-IP> = IP address of TFTP Server (Publisher)

<S-DHCP-SERVER-IP> = IP address of DHCP Server (Publisher)

United States Marine Corps, Communication Training Center, Marine Corps Communication

ElectronicsSchool, Training Command. “How to use Configuration Templates_SWAN-

D_v1.4.doc” Page 1.

Intended Audience: SWAN system users

Due to the highly technical nature of satellite technology, there will inevitably be massive

amounts of information that will be included in professional documents. The sample attempts to

address that information, by simplifying the method of delivery. The above document is another manual

for a different version of the SWAN. The information contained here is a sort of cheat sheet for SWANsystem users. While the sample is somewhat cluttered, there are some positive attributes of the

document. It abandons traditional sentence structure, and adopts a math equation type format (a = b).

This allows readers to quickly scan the document for the information they need. This type of document

would be helpful to professionals and students who need to reacquaint themselves with specific terms

and their corresponding identities.