Upload
jonhaupt
View
216
Download
0
Embed Size (px)
Citation preview
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
7/30/2019 Technical Writing Style Research
http://slidepdf.com/reader/full/technical-writing-style-research 2/13
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.
7/30/2019 Technical Writing Style Research
http://slidepdf.com/reader/full/technical-writing-style-research 3/13
3 | P a g e
Samples from aProfessional Discourse
Community
Jonathan Haupt
7/30/2019 Technical Writing Style Research
http://slidepdf.com/reader/full/technical-writing-style-research 4/13
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
7/30/2019 Technical Writing Style Research
http://slidepdf.com/reader/full/technical-writing-style-research 5/13
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
7/30/2019 Technical Writing Style Research
http://slidepdf.com/reader/full/technical-writing-style-research 6/13
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.
United States Marine Corps, Communication Training Center, Marine Corps Communication Electronics
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/30/2019 Technical Writing Style Research
http://slidepdf.com/reader/full/technical-writing-style-research 7/13
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.
7/30/2019 Technical Writing Style Research
http://slidepdf.com/reader/full/technical-writing-style-research 8/13
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.
7/30/2019 Technical Writing Style Research
http://slidepdf.com/reader/full/technical-writing-style-research 9/13
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.
United States Marine Corps, Communication Training Center, Marine Corps Communication Electronics
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.
7/30/2019 Technical Writing Style Research
http://slidepdf.com/reader/full/technical-writing-style-research 10/13
10 | P a g e
Sample 7:
United States Marine Corps, Communication Training Center, Marine Corps Communication Electronics
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
7/30/2019 Technical Writing Style Research
http://slidepdf.com/reader/full/technical-writing-style-research 11/13
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.
7/30/2019 Technical Writing Style Research
http://slidepdf.com/reader/full/technical-writing-style-research 12/13
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.
United States Marine Corps, Communication Training Center, Marine Corps Communication Electronics
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).
7/30/2019 Technical Writing Style Research
http://slidepdf.com/reader/full/technical-writing-style-research 13/13
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.