3. Good Technical Writers Practice
◦ •Planning
◦ •Clarity
◦ •Brevity
◦ •Simplicity
◦ •Word Choice
◦ •Active Voice
◦ •Committing to Writing as a Process
Writing
Revising
Planning/
Rethinking
4. Clarity: Avoid Jargon
◦ •Jargon: a vocabulary particular to a
place of work (abbreviations, slang)
◦ •Audience familiarity with the topic
determines appropriate use of jargon
◦ Ex. 1: For the first year, the links with
SDPC and the HAC were not connected,
and all required OCS input data were
artificially loaded. Thus CATCH22 and
MERWIN were not available.
◦ Ex. 2: Because some of the links in
the computer system were not
connected the first year, we could not
run all the software codes.
◦ •If you must abbreviate, define the term in its first
occurrence, and put abbreviations in parentheses
◦ Ex: We know that the use of square-root raised cosine
(SRRC) pulses at transmitter and receiver suppresses
inter-symbol interference (ISI) and maximizes the received
signal-to-noise ratio (SNR) in the presence of white noise
◦ •Italicize first occurrence of unfamiliar terms and
define them right away
◦
◦ Ex: In computing, a datawarehouse, also known as an
enterprise data warehouse, is a system used for reporting
and data analysis, and is considered a core component of
business intelligence
Clarity: Define the Unfamiliar
5. Brevity: Use Words Efficiently
◦ •Never use two words when one word
will do.
◦ Ex. 1: OpenAI’s new algorithm, named
GPT-2, is one of the most exciting
examples yet which excels at a task known
as language modeling that was a kind of
training from all resources including
articles, blogs and websites on network
environment.
◦ Ex. 2: The GPT-2 was trained on the task
of language modeling by ingesting
numbers of articles, blogs, and websites
Brevity: Less Is More
◦ • Pare your language down to the
essential message you want to get across to
your readers:
◦ Ex: The development of the GBSM is
assumed that the scatters are arranged in a
geometrical form. That is, we can describe
the AoA and AoD ‘s statistical properties.
The physical principles of reflections,
scattering, and diffractions of waves are
used to develop the GBSM.
6. Brevity: Remove Redundancy
◦ •Combine overlapping sentences when
possible
◦ Ex. 1: Water quality in Hawk River
declined in March. This decline occurred
because of the heavy rainfall that month.
All the extra water overloaded Tomlin
county’s water treatment plant.
◦ Ex. 2: Water quality in Hawk River
declined in March because heavy
rainfalls overloaded Tomlin County
water treatment plant.
Brevity: Most Important First
◦ •Place key information in the main clause
◦ Ex. 1: Wireless operators are being challenged
as never before to add capacity and boost
network performance despite the fast-moving
5G is deployed.
◦ Ex. 2: Capacity and boost network
performance are the challenge as never
before to the wireless operators despite the
fast-moving 5G is deployed.
◦ Ex. 3: The challenge as never before is
capacity and boost network performance
despite the fast-moving 5G is deployed.
7. Simplicity: Use Details Wisely
◦ •Specific details are desirable, but be careful to balance detail with audience needs for
clarity—significance is more important.
◦ Ex. 1: This paper presents an approach to the evaluation of the reverse link capacity of a CDMA cellular voice
in Erlang.
◦ Ex. 2: This paper presents an approach to the evaluation of the reverse link capacity of a CDMA
cellular voice in Erlang, which is a dimensionless unit used in telephony as a measure of offered load
or carried load on service-providing elements [Roger L., 2005]. A single cord circuit has the capacity
to be used for 60 minutes in one hour, full utilization of that capacity, 60 minutes of traffic,
constitutes 1 Erlang.
◦ •Many engineers want to provide as much specific detail as possible, but this can come at
the expense of readers understanding and their main point
◦ Ex. 1: The global volume of SMS are increasing enormously. It was 997,668,775,324 messages in
2005 and it is expected to grow three times as much by 2012.
◦ Ex. 2: The global volume of SMS is grown enormously. It was nearly 1 trillion messages in
2005 and it is expected to grow three times as much by 2012.
8. Language:
Needless Complexity Abstraction
◦ •Avoid too many abstract nouns
◦ Ex. 1: A computational algorithms rely on
repeated random sampling to solve physical and
mathematical problems mainly in classes:
optimization, numerical integration from a
probability distribution.
◦ Ex. 2: With Monte Carlo method, we modeled a
probability distribution of physical and
mathematical problems
9. Language:
Needless Words
(already) existing never (before)
at(the) present (time) none(at all)
(basic) fundamentals now(at this time)
(completely) eliminate period(of time)
(continue to) remain (private) industry
currently(being) (separate) entities
(currently) underway start(out)
(empty) space write(out)
had done(previously) (still) persists
introduced(a new)
mix(together)
Ambiguity
◦ •Choose words whose meanings are
clear
◦ Ex. 1: Each node in routing by forwarding
data for other participates as ad hoc
network does not rely on a pre-existing
infrastructure
◦ Ex. 2: Each node in routing by forwarding
data for other participates because ad
hoc network does not rely on a pre-
existing infrastructure
10. Language: Ambiguity
◦ •Order the words in your sentences carefully
◦ Ex. 1: As AI greatly enhances work flow, processes, and accelerates the smart workplace investments, we see
particularly substantial impacts in the Medical and Bioinformatics as well as Financial Services segments.
◦ Ex. 2: We see particularly substantial impacts in the Medical and Bioinformatics as well as Financial
Services segments as AI greatly enhances work flow, processes, and accelerates the smart workplace
investments.
◦ •Do not overuse pronouns —particularly “it” and “this”— because it is often difficult to identify the
antecedent
◦ Ex.1: The PSM does not describe the channel as in the GBSM but it uses the channel parameters described the
transmission paths.
◦ Ex.2: The PSM does not describe the channel as in the GBSM. Instead, the PSM uses the channel
parameters described the transmission paths.
11. Language: Weak vs. Strong
•Avoid too many “to be”verbs: “is”,“was”, “were”,“has been”,“have been”
•Avoid excess words, which slow comprehension of the main point
made arrangements for arranged
made the decision decided
made the measurement of measured
performed the development of developed
is working as expected works as expected
12. Active Voice:
Strong Verbs
◦ •Technical writers want to communicate as
efficiently as possible, and active voice is
more straightforward and is stronger than
passive voice
◦ Ex 1: The feedthrough was composed of a
sapphire optical fiber, which was pressed
against the pyrotechnic that was used to
confine the charge.
◦ Ex 2: The feedthrough contained a
sapphire optical fiber, which pressed
against the pyrotechnic that contained
the charge.
Natural Sound
◦ •When in doubt, read passages out loud to determine
the natural sound*
◦ Ex 1: AI may speed up the ability to predict accessible
alternatives. A large amount of data used to create a
model involves in. A user is recommended to avoid an
inaccessible access point.
◦ Ex 2: AI may speed up the ability to predict
accessible alternatives. The process usually involves
a large amount of data used to create a model. This
application provides the recommendations for a
user to avoid an inaccessible access point.
◦ *always defer to your professor, your journal, or your company style
guide for use of “I” and “we” in technical paper
13. Unity: focuses on the topic.
Coherence: continuity of the thought.
Adequate content:
Adequate development.
Adequate pattern of organization.
Paragraphs fall into four types; Beginning,
Body, Concluding, and transitional.
Effective paragraphs
A paragraph is a
group of sentences
tied by one main
idea. A paragraph
has:
Structure: A topic
statement that ties all
sentences.
Form: marked by
using indentations.
Length 50 to 250
words, 2-16 sentence.
In technical writing
these paragraphs
need to be effective.
An effective
paragraph should
have some
characteristics as
follows:
14. THE FIRST STEP
IN WRITING A
TECHNICAL
REPORT, ESSAY,
ARTICLE, OR
PRESENTATION
IS TO WRITE A
PARAGRAPH.
A PARAGRAPH
IS A GROUP
OF
SENTENCES
TIED BY ONE
MAIN IDEA.
PARAGRAPHS
HAVE
STRUCTURE,
FORM, AND
LENGTH.
How to write effective
paragraphs?
BEGINNING
(INTRODUCTORY,
STARTING)
BODY (NORMAL
PARAGRAPH IN
THE TEXT)
CONCLUDING
(ENDING,
CLOSING)
TRANSITIONAL
TYPES OF PARAGRAPHS
15. Opening Paragraph
The opening
paragraph
should:
Capture
reader’s
interest.
Announce
the topic.
Define the
problem.
Define the
background.
Present the
thesis
statement.
State
purpose or
scope.
Present the
text contents.
The opening paragraph should have the following structure:
Introduce topic + prepare for the thesis.
or
Write the thesis + shortly develop it.
or
Use both techniques for 2 sentences.
The closing paragraph:
◦ Restates thesis + conclusion.
or
◦ Discusses significance + implications.
or
◦ May call for actions or recommendations.
How to develop
16. Transitional
paragraphs
The transitional paragraph is
usually a short paragraph
consisting of one sentence.
It sums up previous topic and
shows where to go next.
Body paragraphs carry the message of
the text which is usually called a thesis
statement.
The thesis statement is developed
through the whole text. The text
consists of a number of paragraphs.
Each paragraph consists of a topic
sentence and a number of related
sentences developed so that they are
logically tied to the topic sentence.
Body paragraphs
17. How to
develop an
effective
paragraph?
TOPIC SENTENCE is the core.
The other sentences are developed to
stress the topic sentence.
The topic sentence may be place at the
beginning, end or middle of the
paragraph.
The topic sentence controls other
sentences.
These other sentences should follow a
certain pattern.
18. Commonly
used patterns
for
developing
paragraphs
◦ Narration.
◦ Description.
◦ Classification/division.
◦ Definition.
◦ Process.
◦ Analysis (cause and effect).
◦ Comparison/contrast/analogy.
◦ Listing, illustrating.
◦ General-to-particular.
◦ Background.
A combination of more than one method is
possible.
19. Do not forget that after developing the
paragraph it should:
Show
Show unity.
Emphasize
Emphasize
the right
topic.
Show
Show
cohesion.
Include
Include
variety in
the
sentence
form and
structure.
Show
Show
adequate
content.
Show
Show
adequate
develop-
ment
technique.
Show
Show
adequate
pattern of
organiza-
tion.
20. Writing Is a Process
•Good writing
doesn’t
happen
overnight; it
requires
planning,
drafting,
rereading,
revising, and
editing.
•Learning and
improvement
requires self-
review, peer-
review, subject-
matter expert
feedback, and
practice.
•There are
no
shortcuts;
First
Draft/Revised
Draft/Final
Draft
•Plan your
project
before you
begin
drafting.
•Understand
basic qualities
of good
technical
writing; use
the examples
presented to
guide you in
your writing
and revising
process.
•Good
writing is a
habit that
takes time
to develop;
practice
makes
perfect.
Unity is disturbed by grammatical and
sentence mistakes as well as unrelated
thoughts
Cohesion is achieved through maintaining a clear
pattern, and using specific transition elements
within and between the sentences
NOTE
22. Introduction
Will present how to write a technical report
Covers the following standard technical report sections
Ø Summary
Ø Introduction
Ø Theory
Ø Method
Ø Results
Ø Discussion of Results
Ø Conclusions
Is itself structured in this way!
23. Content
Defines the generic features of a technical
report.
• Gives the specific requirements for lab
reports, design documents and dissertations.
• Presents a methodology for writing a report.
• Describes signposting, captioning, quoting,
citing, and referencing.
• Provides references that can be used for
further reading.
25. Theory
• Why write?
• Theory theory
• Standard structure
• Variations on a theme
• Background knowledge
26. Why write?
• Students Must Write
Technical Reports
Lab reports
Group reports
Presentations
Blogs and wiki pages
Web sites
Technical papers
Project poster
Project dissertation
27. Theory theory
• Technical reports have a standard
structure
• Technical reports may not be read “cover
to cover”
• Standard sections have evolved to same
information to be extracted from
document in different levels of detail!
• Repetition and signposting is good.
• Section labelling, figure and table
captioning, equations, references and
citations
28. The Standard Structure
• Summary of the report
- Purpose, approach, main findings in brief (½ – 1 page)
• Introduction
- To the presentation rather than the subject.
- Purpose of study
- Methodology
- Results
- Main findings & conclusions
- Introduction to the presentation itself
29. Reading technical documents
First comes the title,
this tells you lots and lots
then look at the authors,
are they hot shots?
Read the abstract well
it gives an overview
read it three more times
see if this article’s for you
Get to the introduction
- is the experiment tight?
look at its theoretical framework
- is it all right?
It’s gotta have objectives
as is every article’s fate
are their objectives pertinent?
and are they up to date?
Then you’ll find methodology
which shows you how its done
results will come from this
explored through discussion
Lastly is the conclusion
(you should read this first)
and then see their suggestions
for future research
30. Technical writing : template and architype
Writing an introduction
Writing about methodology
Writing about result and discussion
Writing abstract
31. The
Standard
Structur
e
• Conclusions
Ø Purpose of study
Ø Methodology
Ø Results
Ø Main findings & conclusions
Ø Further work
• References
All the sources used and cited in the body of the
report.
• Appendices
Supplementary or more detailed information that
supports the report
32. Front and End Matter
• Give further structure and information to the
report
• Front matter
Table of Contents
Table of Figures
Table of Tables
Abbreviations
• End matter
Glossary
Index
• Should be automatically generated
33. Variations on a Theme
• Different reports will have different structures
• E.g.
Lab report
Dissertation
Software design Document
• Refer to references for general guidelines
• Follow your publisher’s or institution’s
guidelines for specific cases
34. Lab Report Structure
• As standard +
Theory
Method or Experimental Procedure
Results
Discussion of Results
• It is acceptable to use “mini reports” if separation
of Theory/Method/Results and Discussion would
otherwise make structure awkward.
35. Dissertation
• As Standard +
Background and/or Literature Review
Method
Results
Discussion
• Detailed Front and End Matter
E.g. Table of contents
Table of figures
Appendices
37. Theory
in a Lab
Report
• Background is what is known or assumed
• Sets context for specifying what results there will be and context
for their discussion.
• States what is expected from the experiment or study
• May (should?) include properly cited evidence of wider reading
than contents of lecture notes, lab script.
• You can cite the script where the script provides sufficient detail.
• You must include development of formulae that are not given in
the script that you will later rely on in the discussion!
38. Background for a
Dissertation
• Assumptions
• Basic “textbook” knowledge of the field
• State of the art prior to the work
• Detailed discussion of any of the
available
technical literature
text books
journal articles
conference proceedings
web sites
• that added to your knowledge of the
39. Background for a Software
Design
Document
• Review of existing solutions
• Review of related software systems
• Justification for choice of programming
languages and frameworks
• Design methodologies
• Non functional specifications
40. Introduction (Contents)
• Theory
• Method: How to repeat yourself, Signposting, Numbering, Citations and
References, Writing a method
• Results
• Discussion of Results
• Conclusions
• References
41. How to write a report
• Start in the middle
You have done the work so you know what your
approach was.
You have the results so you just have to write them
up!
Ensure that you understand the background, write
it up and use it to evaluate the results.
Gather your references and ensure that they are
cited in the background sections and other sections
as appropriate.
Write the conclusions and the introduction (in that
order)
Write the summary
42. Repetition
is Good!
• Form of technical report has developed to allow different classes
of readers to make use of the materials in different ways:
- Only summary may be read by a researcher lookingfor information
or a manager seeking an “executive summary”.
- Only conclusions or introduction may be read by someone
interested in the subject but only wanting to adopt the main
findings.
- The whole document may be read by someone wishing to follow-
up on the work published.
• It is important that each part tells the same story at the
appropriate level of detail.
• Repetition and signposts help the reader who is not reading the
document sequential
43. How to Repeat Yourself
• Say what you will say (in brief) in the
Summary
• Say what you will say (in more detail) in
the introduction
• Say what you have to say (in full in the
body) with signposting
• Say what you have said (in the conclusions)
• Emphasise the good bits in an extended
abstract or executive summary
44. How to Signpost
• Open each section with a statement of context:
In the [last section] we ….
In [this section] we now …
• Close each section with a statement of context:
In this [section] we ….
In the [next section] we will …
• Provide cross references
As we saw in [a previous section] …
As we will show in [a later section] …
45. Numbering
• Numbering important parts of the report helps with
signposting
Figure 2 shows ….
Better than the figure on page 3 shows
• Things that should usually be numbered
Parts, Chapters and Sections
Figures and Tables
Equations
• Things that can be numbered
46. Number Sections
• It is easier to use signposting if you label your sections and subsections.
• Dissertation or larger document
Part I
• Chapter 1.
– Section 1.1
» Sub section 1.1.1
• Report or shorter document
Section 1
• Subsection 1.1
– Sub-subsection 1.1.1
• Word processors can make section labelling automatic and cross-referencing semi-automatic.
Learn to use those features.
• Local rules often override general guidelines
47. Figures
• Give all figures a numbered caption
• Refer to figure in text. “Figure 1 shows a document.”
• Use auto-captioning and cross-referencing.
48. Tables
• Give all tables a caption. Caption goes above table.
Table 1: Fee fie for fum
• Refer to table in text. “Table 1 enumerates useful words beginning
with ‘f.’”
• Use auto-captioning and cross-referencing.
49. Equations
• Give all equations a label
• Refer to equation in text. “Equation (1) shows the formula
for a quadratic.”
• Use your word processor’s equation editor to
get auto-captioning and cross-referencing.
50. Citations and References
• Why cite at all?
• A rich reference list is considered evidence of wider reading.
• Critical appraisal of the references with citations in the body of the
report is evidence of your understanding of the materials and how
your work builds on from them.
• Your cited sources provide a frame of reference against which you
can evaluate your report’s contribution to human knowledge
51. Citations
Two main styles:
• Numeric
According to Shakespeare [1] winter’s discontent is now made glorious
by “this son of York”.
“Now is our winter of discontent made glorious summer by this son of
York” [1].
• Symbolic
According to Shakespeare [1597] winter’s discontent is now made
glorious by “this son of York”.
“Now is our winter of discontent made glorious summer by this son of
York” [Shakespeare, 1597].
52. Referencing
- Numeric Style: [1] William Shakespeare, Richard III (Act I, Scene I), Quarto 1,
1597.
+ Easy to use if references do not have to be sorted
+Difficult to maintain if references need to be presented as a sorted list.
- Symbolic: (Harvard) Style Shakespeare, William 1597. Richard III (Act I, Scene I),
Quarto 1.
+ Easy to maintain a sorted list of references.
+ More verbose when citing.
- References at end of document, Poor support for “End notes” in some word
processors
- Different publications often have different styles
- Consider use of a bibliographic database and citing tool to automate citing and
formatting of references.
53. Quoting
• Never quote documents without citing sources.
• Copy-and-paste of large amounts of text, even with
quotation marks and full attribution is considered
plagiarism.
• If you like what someone had to say on a subject, rewrite
it in your own words!
54. URLs
• With more of the world’s knowledge accessible via the Internet it is
unrealistic to ban URLs from
reference lists.
• Do not rely solely on hyperlinks to present URLs
A paper report will not be read on a browser!
Cite them like any other resource
• Cite them as you would a book or article.
• Use as much detail as possible:
[1] William Shakespeare, Richard III. Online at URL:
http://www.gutenberg.org/catalog/world/readfile?fk_files=53 (Project
Gutenberg., 2002)
55. References
and Further
Reading
• In academic circles, the References
section could contain a complete list of all
sources cited in the body of the report.
• Other sources that you have read and that
have helped inform your work but which you
have not cited should be included in a
Bibliography or a Further Reading section.
• References are essential to understanding
your work. Bibliographies are sources that
were useful to you and therefore may be
useful to your readers.
56. Writing a
Method
• You are reporting what you did so use past tense!
• Do not quote from the lab script:
Wrong: “take measurements of x and record results in your lab
book”
Right: “we took measurements of x and recorded the results in
our lab book”
It is acceptable to refer to the instructions if you did not divert
from the suggested method, but cite the original source
We performed x as suggested on Section y (page 2) of the lab
handout [2]
57. Passive
Voice?
• Some publishers prefer and objective tone and
“passive voice”
Ø“Measurements were taken of x and the results
were recorded in a lab book”
• You and your readers may find this a bit
awkward
• Use it if you have to!
58. Results
• Results section presents your findings.
• Use tables, figures and equations as
appropriate.
• Textual commentary is needed to tie
results to method.
• Provide explanation if necessary.
• Usually easiest section to write (if you
recorded the results carefully!)
59. Discussion of Results
• Compare results to expected results
• Account for any differences
Ø Experimental procedure wrong
Ø Accuracy of measurements
• Differences may point to inaccuracies in the theory section and may
point to future work.
Ø “This result can be explained by experimental error” is not an
explanation!
• Be honest, a result that does not match the theory is itself a useful
result!
• If there are questions in the lab script, they should be answered in
this section.
60. Conclusions
• Remind the reader of what you were trying to achieve.
• Outline the theory, method, results and discussion
• Attempt to tie together the theory, results and discussion.
Ø Highlight the places where the theory was correct
Ø Highlight the places where the theory was incorrect
Ø Make suggestions for further work.
• Ensure that the conclusions stands alone because it may
be the only part to be read!
61. References and Further Reading
- Shakespeare, William 1597. Richard III (Act I, Scene I), Quarto 1. Online at URL:
http://www.gutenberg.org/catalog/world/readfile?fk_files=53 (Project Gutenberg.,
2002)
- Newton, Sir Isaac, 1675. Letter to Robert Hooke, February 5. As quoted online at URL:
http://www.quotationspage.com/quotes/Isaac_Newton/ (The Quotationspage.com)
- Barrass, Robert 2002. Scientists Must Write: A Guide to Better Writing for Scientists and
Engineers. Routlege Study Guides, Routledge Falmer. ISBN: 0415269962 . [In the Library
T11>Bar]
- Rosenberg, Barry 2005. Spring into Writing for Engineers and Scientists, Addison Wesley.
ISBN: 0131498630.
- Technical Writing, Library Call Number T11.
- University of Wales Swansea, Student Services Web Site, Study Skills