CS4524 Professional Topics

1
CS4524 Professional Topics

• Writing Reports - Part 2
• Writing Effectively
• If a man can group his ideas, then he is a writer
  (RL Stevenson)

2
Overview

• Writing effectively is all about
• Structuring your writing well
• Using the right voice, person and tense
• Using the right word/phrase at the right time
• Using strong statements (without overdoing it)
• Linking successive sentences into paragraphs
• Writing fluidly varying sentence
  length/structure
• Taking your readers into account

3
Choosing A Strong Title

• A strong title is important
• It should briefly describe the work
• It should encourage the reader to read on
• Good/Bad examples (?)
• How I Did It! (!)
• Database Interoperability (?)
• Fair Job-Scheduling on Beowulf Clusters (?)
• It may take a while to get it just right!

4
Structuring Your Report

• Like presentations, technical writing should be
  well-structured Beginning, Middle, End.
• Often the Middle section may vary.
• E.g. Methods ? Design Implementation
• May have many more subsections than a journal
  article - depends on size of report
• An Index helps the reader navigate.
• A well-structured report is easier to read.

5
Planning The Structure

• 1. Introduction
• 1.1 Background
• 1.2 Previous Approaches
• 1.3 My New Approach
• 2. Design
• 3. Implementation
• 4. Testing
• 5. Discussion Conclusions

6
Using Informative Headings

• Using only the index, the reader should get a
  very good idea of what the report is all about
• Which do you think is better (and why) ?
• a) 2.2 The GUI
• b) 2.2 GUI Design Choices
• c) 2.2 A Novel Choice of GUI
• d) 2.2 A PHP-Based GUI
• e) 2.2 GUI-Building with PHP
• Good sub-headings make it easy to start writing!

7
Good Layout Guidelines

• Good report layouts should
• use large fonts for main section headings
• use smaller fonts for subsections
• have adequate spacing around headings
• have numbered sections subsections
• separate figures/tables from text.
• LaTeX/Word can do all this automatically.

8
Figures, Graphs Tables

• Each figure etc., should be stand-alone
• Reader should be able to understand them without
  referring to the main text
• Each should have a numbered caption
• Captions may include an explanation
• Label all axes, colours, line styles etc.
• Tables can have footnotes

9
Example Figure Citation

• In an eclipse of the sun, the disc of the moon
  completely obscures the body of the sun. However,
  the suns corona, or outer atmosphere, becomes
  visible during totality. Figure 1 shows a NASA
  photograph of the corona, taken from South
  America.

Figure 1 NASA photograph of the suns corona.
10
Using Fonts Effectively

• Use a serif font such as Times Roman for printed
  documents.
• Can use a different font for equations or code
  fragments, but be consistent.
• Usually a mono-spaced font such as Courier is
  best for code fragments.
• Consider presenting code fragments as figures.

11
Which Voice for the Author?

• For the author, I or we (active voice) is OK,
  but be consistent
• I/We implemented the GUI using
• Many authors use royal we (We gt I)
• Some authors prefer the passive voice
• The GUI was implemented using
• But sometimes this can cause problems
• In the authors opinion

12
Which Person for the Reader?

• Many authors use the third person (he/she, they)
• If the user makes a mistake, he can click Undo
• He or she, s/he, or she are OK, but dont
  overuse
• Beware of grammatical errors
• If the user makes a mistake, they can click
  Undo (!)
• Second person (you) is more informal
• If you make a mistake, simply click Undo
• Second person is often good for User Manuals

13
Which Tense to Use?

• Reports usually use past tense, but be
  consistent
• When the source was compiled with full
  optimisation, the program ran much faster. Timing
  trials showed that
• When the source is compiled with full
  optimisation, the program runs much faster.
  Timing trials show that
• For sequences of events, past tense is better
• The program was developed, compiled, and then
  executed.

14
Saying What You Mean

• You have to start on your report soon
• My report badly needs to be written
• My report needs to be written badly
• My report needs to be written urgently
• My report urgently needs to be written
• So read back what you just wrote
• Does it say what you meant to say?
• Is there a better / less ambiguous phrase?

15
Stronger/Weaker (Spin)

• Often, we have a choice of phrases with different
  strengths at our disposal, e.g.
• Solved gt addressed gt worked around
• Try to choose an appropriate strength
• I solved the network problem (strong)
• I addressed ... (looked at it)
• I worked around (avoided it)
• Dont claim too much, but dont undersell

16
More Spin (Persuasion)

• Compared to the method of Newton et al. our
  new algorithm...
• Our software out-performs their code.

• method gt cookbook
• algorithm gt scientific
• software gt engineered
• code gt hacked
• We build software
• They write code

17
Supporting Your Argument

• Avoid making bold, unsupported statements
• Java is very slow language.
• Try to add support with a justification
• Because Java byte-code is interpreted, Java
  tends to be quite slow
• Or cite a reference (external authority)
• Java is provably slow (Gates et al., 1992).

18
Using References

• Citing relevant references adds support
• Adopt a consistent style for citations
• Java is slow 1.
• Java is slow (Gates et al., 1992).
• Java is slow Gat92.
• Then, have a corresponding Bibliography
• Word/LaTeX can automate this

19
Pretentious? Moi?

• Pretentiousness is easy to spot correct
• Elevated temperatures in the propellant storage
  compartments facilitated an unscheduled
  disassembly of the orbiter.
• Who is this supposed to impress?
• Whats wrong with
• The rocket exploded because the fuel tanks
  became too hot.

20
Pretentious Words Phrases

• ability words are often pretentious
• Manufacturability ease of manufacture
• Implementability easily implemented
• Scaleability (probably OK check dictionary!)
• So are business speak phrases e.g.
• Customer-facing
• Next-generation
• Mission-critical

21
Barry Turners Instant Jargon Generator
Ref Turner, B.T., Effective Technical Writing
and Speaking, Business Books Ltd, 1974.
22
Using Paragraphs Topics

• The first sentence in a paragraph is the most
  important it identifies the topic
• Dear Aberdeen City Council,
• When I reverse out of my garage, I cannot see
  the traffic because of a large overgrown tree in
  the street in front of my house. Please can you
  remove it.
• What is the council supposed to remove?
• Here, the topic is a tree, but the final it
  actually refers to house!

23
Better Paragraph Structure

• A better letter to the council
• Dear Aberdeen City Council,
• There is a large overgrown tree (topic) in the
  street in front of my house. The tree severely
  obstructs my view (problem) when I reverse my car
  into the street. This poses a danger to myself
  and other road users (implied responsibility).
  Please would you remove the tree (solution)
  immediately (urgency).
• Note Beginning, Middle and End structure

24
Play Your Best Card First

• Some writers bury the most important point by
  trying to build up to a climax
• So, despite all of the difficulties mentioned
  above, I finally implemented a successful
  system.
• But readers wont stay with it for the punch
  line
• Better, state main point first, then
  explain/qualify
• The system was implemented successfully
  However, several difficulties had to be overcome
  These were

25
Being Fluid

• In fluid writing, each sentence links to the next
• The effect of concept1 is influenced by
  concept2. Concept2 can depend on concept3.
  Therefore, reducing concept3 might help solve the
  main side effects of concept1
• Reduce the number of new ideas or facts in each
  sentence
• Try to vary sentence length structure

26
Mt St Helens Eruption 1980
27
Fluid But Stagnant Writing

• Mount St. Helens erupted on May 18, 1980. A
  cloud of hot rock and gas surged northward from
  the collapsing slope. The cloud devastated more
  than 500 square kilometres of forest and lakes.
  The effects of Mount. St. Helens were well
  documented with geophysical instruments. The
  origin of the eruption is not well understood.
  Volcanic explosions are driven by a rapid
  expansion of steam. Some scientists believe that
  steam comes from groundwater heated by magma.
  Other scientists believe the steam comes from
  water originally dissolved in the magma. We need
  to understand the source of steam in volcanic
  eruptions. We have to determine how much water
  the magma contains.

28
Varying Sentence Structure

• Mount St. Helens erupted on May 18, 1980.
  With its slope collapsing, the mountain emitted a
  cloud of hot rock and gas. Within minutes, the
  cloud devastated more than 500 square kilometres
  of forest and lakes. Although the effects of the
  eruption were well documented, the origin is not
  well understood. However, it is known that
  volcanic explosions are driven by a rapid
  expansion of steam. Recently experts have been
  researching the source of this steam. Is it
  groundwater heated by magma, or water originally
  dissolved in the magma itself? To understand this
  process, we need to determine how much water the
  magma contains.

29
Sentence Openings

• The previous example illustrates several ways to
  start a sentence (technical term in brackets)
• Mount St Helens erupted (subject-verb)
• With its slope collapsing, (participial phrase)
• Within minutes, (prepositional phrase)
• Although the effects, (introductory clause)
• Recently, (transition)
• Is it groundwater? (question)
• To understand the source (infinitive phrase)

30
Not Varying Sentence Length

• On the morning of May 18, a strong earthquake
  shook Mount St. Helens, causing the volcanos
  cracked and steepened north side to slide away
  (24). Photographs taken during these early
  seconds, together with other information, showed
  that the blast originated 500 metres beneath a
  bulge on the north face (25). Photographs and
  time of destruction of a seismic station
  established the velocity of the blast to be about
  175 metres per second (22). Of significance, the
  volume of new magmatic material ejected in the
  blast (about 0.1Km3) equals the volume of the
  bulge (22).

31
Varying Sentence Length

• On the morning of May 18, a strong earthquake
  shook Mount St. Helens, causing the volcanos
  steep and cracked north side to slide away (24).
  Photographs showed that the blast began beneath a
  bulge on the north face (13). When coupled with
  other information, these photographs established
  the depth of the blasts origin to be 500 metres,
  and the blast velocity to be 175 metres per
  second (28). The measured volume of the ejected
  magmatic material was about 0.1Km3 (11). This
  volume equals the volume of the bulge (8).

32
Using Signpost Words

• Signpost words are hints telling the reader
  whats coming next
• There are four main conclusions. First,
  conclusion1 is the most important. Second, we
  present conclusion2. Third, conclusion3 is also
  important. Finally, conclusion4 may also be
  significant in some cases.
• For more than 3 or 4 items, a list (numbered or
  bulleted) is probably better.

33
Signposting an Argument

• Certain words phrases can help signpost the
  pros cons of an argument
• On the one hand, we have positive1, but on
  the other hand, we have negative1. Additionally,
  negative2 can be a problem. However, positive2
  and positive3 outweigh negative2. Of course,
  negative3 still has to be considered.
  Nonetheless, the positives outnumber the
  negatives, and so overall we arrive at the
  correct conclusion. Furthermore, we were right
  all along!
• Try to spot similar signposting the next time you
  read something (theyre very common in review
  articles)

34
Rome Wasnt Built in a Day

• Writing well is a skill that requires practice.
• Write the first draft quickly get ideas down!
• Now, try reading the whole thing rapidly.
• Dont stop to fix anything
• just mark any problem areas with a pencil.
• Then, go back and re-work the problems.
• Ideally, get a friend to proof read for you.
• Make final changes but dont tinker.