Post on 11-Mar-2020
1
Research Methods:Technical Writing
James Gainjgain@cs.uct.ac.za
Research Methods
Outline
Approaching WritingGetting PublishedSome Key Elements ofTechnical StyleYour ReportA Research Paper
Research Methods
Why Learn to Write Well?
It takes lots of practice, so why bother?Because it is one of the most valuable life-longskills
Most CS careers require writing:Research - proposals, research notes, literaturesurveys, paper reviews, conference and journalpapers, thesesIndustry - code comments, documentation,reports, memos
The purpose is communication notobfuscation
Research Methods
How to begin?
Bottom-upDescribe details and link them togetherLeads to unstructured mess
Top-downStart with structure and flesh outLeads to shifting structure as you progress
Bi-directionalWrite notes as you do research (bottom-up)Then structure your thesis/paper around a message (top-down)Then fill in the structure with details (bottom-up)
2
Research Methods
High-level Issues
Your writing should have a messageAn argument (hypothesis) for which yourresearch provides evidenceMessage must be reflected in the title, abstract,introduction, conclusion and body of yourwriting
Aiming to be understood is not sufficient:Write so that you cannot be misunderstoodAssume your audience is intelligent but:
(a)ignorant and (b) given to misunderstandingState key ideas transparently, prominently andoften
Research Methods
Outline
ApproachingWritingGettingPublishedSome KeyElements ofTechnical StyleYour ReportA ResearchPaper
Research Methods
Getting Published -The FlowChart
Submit
Referees
Editor’sDecision
Accept
In Print at Last!
Reject
Revise
StillRelevant
TrySomewhere
Else
Yes
No
RevisedManuscript
Try Again!
Research Methods
Submission
Submission:
• Don’t bother too muchwith ‘Instructions toAuthors’
• Never submit tomultiple destinationssimultaneously
Submit
Referees
Editor’sDecision
Accept
In Print at Last!
Reject
Revise
StillRelevant
TrySomewhere
Else
Yes
No
RevisedManuscript
Try Again!
3
Research Methods
Refereeing
Refereeing:
• Single or Doubleblind
• Review quality isoften proportional toreview length
Submit
Referees
Editor’sDecision
Accept
In Print at Last!
Reject
Revise
StillRelevant
TrySomewhere
Else
Yes
No
RevisedManuscript
Try Again!
Research Methods
Acceptance
On Acceptance:
1. Minor changesand formatting
2. Galley proofs
3. Receive journalcopies or off-prints
Submit
Referees
Editor’sDecision
Accept
In Print at Last!
Reject
Revise
StillRelevant
TrySomewhere
Else
Yes
No
RevisedManuscript
Try Again!
Research Methods
Revision
Revision Options:• Treat as a rejection
• Make at least 80% ofthe suggestedchanges (in a collageformat)
• Argue the toss (withthe editor not thereviewers)
Submit
Referees
Editor’sDecision
Accept
In Print at Last!
Reject
Revise
StillRelevant
TrySomewhere
Else
Yes
No
Try Again!
RevisedManuscript
Research Methods
Rejection
On Rejection:
• Damage dependson the reviewingdelay and comments
• May have to submitto a less prestigiousdestination
Submit
Referees
Editor’sDecision
Accept
In Print at Last!
Reject
Revise
StillRelevant
TrySomewhere
Else
Yes
No
Try Again!
RevisedManuscript
4
Research Methods
Outline
Approaching WritingGetting PublishedSome Key Elements of Technical StyleYour ReportA Research Paper
Source: W. Hopkins,“Guidelines on Style forScientific Writing”, SportsScience, 3(1), 1999
Research Methods
The Basics
Submit by the deadlineKeep to the length restrictions
Do not narrow the marginsDo not use 6pt font
On occasion, supply supporting evidence(e.g. experimental data, or a written-outproof) in an appendix
Always use a spell checker
Research Methods
Visual Structure
Give strong visual structure to your paperusing
sections and sub-sectionsbulletsitalicslaid-out code
Find out how to draw pictures, and use themCan the reader understand the paper usingthe diagrams (and captions) alone?
Research Methods
Citations
Serve to:Acknowledge the work of othersDirect the reader to additional sources ofinformationAcknowledge conflicts with other resultsProvide support for the views expressed in thepaperBroadly, place a paper within its scientificcontext, relating it to the present state of the art
An unsupported statementSure sign that either a reference is needed or asupporting argument
5
Research Methods
Citation Styles
There are many styles. Choose one and apply itconsistently.Example: ACM Style
Journal - Anderson, R.E. Social impacts of computing:Codes of professional ethics. Social Science ComputingReview 10, 2 (Winter 1992), 453-469.Conference - Mackay, W.E. Ethics, lies and videotape, inProceedings of CHI '95 (Denver CO, May 1995), ACM Press,138-145.Book - Schwartz, M. Guidelines for Bias-Free Writing. IndianaUniversity Press, Bloomington IN, 1995.Citing in the text - [1] [3, 15]
Other styles include Harvard, IEEE
Research Methods
Exercise: Citations
Place ACM-style citation labels in the following textwhere required:
“The field is well researched and Bechmann and Milliron et al.provide useful surveys. Typically, deformations are specified bymanipulators, including parametric hyperpatches, points, curves,twisting frames and 2-1/2 D surfaces.”
Solution:“The field is well researched and Bechmann [1] and Millironet al. [2] provide useful surveys. Typically, deformations arespecified by manipulators, including parametrichyperpatches [3, 4], points [5], curves [6, 7], twisting frames[8] and 2-1/2 D surfaces [9].”
Research Methods
Viewpoint Usage
Rule:Never use the 1st person singular (‘I’)
Third person is preferredNot - “I found out when I ran pilot experiments that theinitial design suffered from my personal bias.”Rather - “On running pilot experiments it was found that theinitial design suffered from experimenter bias.”This sometimes necessitates passive voice (subject last)
Use of 1st person plural (‘We’)Use where the sentence would otherwise become toocontortedEven if you are the only author
Research Methods
Exercise: 3rd Person
Convert to a technical viewpoint:“As I approached the road that cut through the New RiverMesa, I noticed that there were seven layers. Looking atthe lowermost layer it seemed to me to be an arkosicsandstone.”
Solution:“Where the road cut through the New River Mesa, sevenlayers were noticeable. The lowermost of these layersseemed to be an arkosic sandstone.”
6
Research Methods
Use the Active Voice
The passive voice is “respectable” butit DEADENS your writing. Avoid.
We can see that...It can be seen that...
This might seem like atype error
It might be thoughtthat this would be a
type error
We wanted to retainthese properties
These properties werethought desirable
We ran 34 tests34 tests were run
YESNO
“We” =you and
thereader
“We” =the
authors
Research Methods
Use Simple, Direct Language
The ball moved sidewaysThe object under study was
displaced horizontally
The garbage collector wasslow
It could be considered thatthe speed of storage
reclamation left somethingto be desired
Find outEndeavour to ascertain
YearlyOn an annual basis
YESNO
Research Methods
Reminder: Tense
Tense shows position in time (past, present, future)Types:
Simple (most basic)Continuous (ongoing)Perfect (completed)Perfect continuous (ongoing actions that will be completed atsome definite future time)
will have exploredwill be exploringwill/shall exploreFuture
has exploredis exploringexplore/sPresent
had exploredwas exploringexploredPast
PerfectContinuousSimple
Research Methods
Tense Usage
Present Simple and Perfect predominate in scientificwriting:
The work exists now and is timely but may have started inthe pastExample - “From-point visibility algorithms are less costlycomputationally than from-region approaches”
Except:Use past tense to report results.
• “in our experiments we found that …”But use present tense to discuss them.
• “a simple explanation of these findings is that …”
7
Research Methods
Exercise: Conciseness
Reword the paragraph to make it concise:“Virtually all experienced writers agree that any written expression thatdeserves to be called vigorous writing, whether it is a short story, an articlefor a professional journal, or a complete book, is characterized by theattribute of being succinct, concise, and to the point. A sentence--nomatter where in the writing it occurs--should contain no unnecessary orsuperfluous words, words that stand in the way of the writer's directexpression of his or her meaning and purpose. In a very similar fashion, aparagraph--the basic unit of organization in English prose--should containno unnecessary or superfluous sentences, sentences that introduceperipheral content into the writing or stray from its basic narrative line. It isin this sense that a writer is like an artist executing a drawing, and it is inthis sense that a writer is like an engineer designing a machine. Goodwriting should be economical for the same reason that a drawing shouldhave no unnecessary lines, and good writing should be streamlined in thesame way that a machine is designed to have no unnecessary parts,parts that contribute little or nothing to its intended function.”
Research Methods
Solution: Conciseness
“Vigorous writing is concise. A sentence should contain nounnecessary words, a paragraph no unnecessary sentences,for the same reason that a drawing should have nounnecessary lines and a machine no unnecessary parts.”34 wordsBe careful not to overdo it. Some concepts need to beexplained in detail.
Research Methods
Flow of Ideas (Cohesion)
At a sentence levelOne sentence linked to the next
At a paragraph levelFirst sentence sets the topicNo unlinked ideas in the paragraph
At a section levelOutline firstDon’t repeat or contradict other sections
At a document levelCreate a logical and cohesive outline supporting themessageSet the draft aside for a while, get others to read it
Research Methods
Outline
Approaching WritingGetting PublishedSome Key Elements of Technical StyleYour ReportA Research Paper
8
Research MethodsTell a story
Project Write-up
This is what determines your mark!(Very Last) Abstract
1. (Last) Introduction: Aims, importance, outline2. (First & ongoing) Background3. (Second) Theory/Algorithms4. (Third) Application of Theory/Algorithm
Implementation5. (Fourth) Experiment: Design + Results + Discussion
of Results6. (Last) Conclusion — Tie up with aims:
“we said we would and we did”, except (oops) some didn’twork, and (wow) we found an amazing unexpectedthing, but now we would do this … (future work) Research Methods
Outline
Approaching WritingGetting PublishedSome Key Elementsof Technical StyleYour ReportA Research Paper
Source: S. Peyton Jones,“How to write a great researchpaper”, Microsoft Research,Cambridge
Research Methods
Writing a Paper
The purpose of writing a researchpaper is to communicate your ideas toyour peers
This is more limited than the projectresearch report or dissertation or thesis
Each paper must have a central ideaWith evidence to support it
Research Methods
The Idea
A re-usable insight, useful to the readerFigure out what your idea isMake certain that the reader is left in nodoubt about the idea or contribution
Be 100% explicit:“The main idea of this paper is....”“In this section we present the main contributionsof the paper.”
Many papers contain good ideas, but donot distil what they areThe reader is interested in ideas not artefacts
9
Research Methods
Here is a problemIt’s an interesting problemIt’s an unsolved problemHere is my ideaMy idea works (details, data)Here’s how my idea compares toother people’s approaches
Your narrative flow
I wish Iknew howto solve
that!
I see howthat works.Ingenious!
Research Methods
Structure
TitleAbstractIntroductionThe problemMy ideaThe detailsRelated workConclusionsReferences
(1000 reader)(4-8 sentences, 100 readers)(1 page, 100 readers)(1 page, 10 readers)(2 pages, 10 readers)(4 pages, 3 readers)(1 page, 10 readers)(0.5 pages, 20 readers)(1 page, 10 readers)
Research Methods
Abstract: structure
Write the abstract lastUsed by program committeemembers to decide which papers toreadFour sentences [Kent Beck]
State the problemSay why it’s an interesting problemSay what your solution achievesSay what follows from your solution
Research Methods
Abstract: example
Many papers are badly written and hard tounderstandThis is a pity, because their good ideas maygo unappreciatedFollowing simple guidelines can dramaticallyimprove the quality of your papersYour work will be used more, and thefeedback you get from others will in turnimprove your research
10
Research Methods
Introduction: structure
Describe the problemProviding context
State your contributionsExplicitly
And that is all
Use an exampleto introduce the
problem
Bulleted list ofcontributions
Research Methods
Introduction: state yourcontributions
Write the list of contributions firstThe list of contributions drives the entire paper:
The paper substantiates these claims
Reader thinks:“Wow, if they can deliver on this … I’d better read on”
Do not leave the reader to guess what yourcontributions are!
“In this paper we …”“We explain precisely what … surprisingly this has not beendone before”“… articulating this is one of our main contributions”
Research Methods
Introduction: contributionsshould be refutable
YES!NO!
We have built a GUI toolkit inWizWoz, and used it to implement atext editor (Section 5). The result ishalf the length of the Java version.
We have used WizWoz inpractice
We prove that the type system issound, and that type checking isdecidable (Section 4)
We study its properties
We give the syntax and semantics ofa language that supportsconcurrent processes (Section 3). Itsinnovative features are...
We describe the WizWozsystem. It is really cool.
Research Methods
Introduction: No “rest of thispaper is...”
Not:
Instead, use forward references fromthe narrative in the introduction.
The introduction (including thecontributions) should survey the wholepaper, and therefore forward referenceevery important part
“The rest of this paper is structured as follows.Section 2 introduces the problem. Section 3... Finally, Section 8 concludes”.
11
Research Methods
Related Work
TitleAbstractIntroductionRelated WorkThe problemMy ideaThe detailsConclusionsReferences
Relatedwork
Your reader Your idea
We adopt the notion of transaction fromBrown [1], as modified for distributedsystems by White [2], using the four-phaseinterpolation algorithm of Green [3]. Ourwork differs from White in our advancedrevocation protocol, which deals withthe case of priority inversion as describedby Yellow [4].
Research Methods
Related Work: later is better
Problem 1:
the reader knows nothing about theproblem yet; so your (carefully trimmed)description of various technical tradeoffs israther incomprehensible
Problem 2:
describing alternative approaches getsbetween the reader and your idea
But delaying related work isunconventional I feel
tired
I feelstupid
Research Methods
The Body
TitleAbstractIntroductionThe problemMy ideaThe detailsConclusionsReferences
(1 page, 10 readers)(2 pages, 10 readers)(4 pages, 3 readers)
Research Methods
The Body: Presenting the Idea
The idea:“Consider a bifircuated semi-lattice D, over ahyper-modulated signature S. Suppose pi is anelement of D. Then we know for every such pithere is an epi-modulus j, such that pj < pi.”
Sounds impressive ... butSends readers to sleepIn a paper you MUST provide the details,but FIRST convey the idea
12
Research Methods
The Body: Idea 1st, Details 2nd
Explain it as if you were speaking tosomeone using a whiteboardConveying the intuition is primary, notsecondaryOnce your reader has the intuition, shecan follow the details (but not viceversa)Even if she skips the details, she stilltakes away something valuable
Research Methods
The Body: Putting the reader first
Avoid the Journey:Do not recapitulate your personal journey ofdiscovery. This route may be soaked with yourblood, but that is not interesting to the readerInstead, choose the most direct route to the idea
Use Examples:Introduce the problem, and your idea, usingexamples and only then present the generalcase
Research Methods
The details: evidence
Your introduction makes claims
The body of the paper provides evidence tosupport each claim
Check each claim in the introduction,identify the evidence, and forward-reference it from the claim
Evidence can be:Analysis and comparison, theorems,measurements, case studies, experiments
Research Methods
Structure
TitleAbstractIntroductionThe problemMy ideaThe detailsRelated workConclusionsReferences
(1 page, 10 readers)(0.5 pages, 20 readers)(1 page, 10 readers)
13
Research Methods
Related work
Fallacy:To make my work look good, I have to makeother people’s work look bad
Giving credit to others does not diminish thecredit you get from your paper
Warmly acknowledge people who have helpedyouBe generous to the competition. “In his inspiringpaper [Foo98] Foogle shows.... We develop hisfoundation in the following ways...”Acknowledge weaknesses in your approach
Research Methods
Credit is not like money
Failing to give credit to others can kill yourpaper
If you imply that an idea is yours, and thereferee knows it is not, then either
(a) You don’t know that it’s an old idea (bad)(b) You do know, but are pretending it’s yours
(worse)
Conclusion and Future Work:Be brief and too the point
Research Methods
In Conclusion
Technical writing is a skill that must be honedthrough practice
Different from other forms of writingDeliver a coherent message
Identify your key ideaUse examples
Make your contributions explicit