Upload
ian-alpa
View
217
Download
0
Embed Size (px)
Citation preview
7/29/2019 TechWriting Guidelines
1/75
M.S.Ramaiah School of Advanced StudiesVKBMDD 1
Guidelines
forTechnical Writing
Vinod K. Banthia
M .D.Deshpande
7/29/2019 TechWriting Guidelines
2/75
M.S.Ramaiah School of Advanced StudiesVKBMDD 2
General Issues
Why a lecture about writing?Surely, any literate can write. Why talk about Writing?
Any body can sing. But, can we get an audience?
Writing is for communication? Can we get readers?
Writing is a SKILL .
Good writing is an ART. More so Technical Writing.
There may be those who are born or gifted writers.
Others have to LEARNand PRACTICE.
7/29/2019 TechWriting Guidelines
3/75
M.S.Ramaiah School of Advanced StudiesVKBMDD 3
Contents
Introduction
General Issues
Basic Requirements
Elements of Technical Writing
Writing a Project Report
Selecting a ProjectComposing the Title - Writing the IntroductionBody of
the ReportProblemMethodology and ToolsCollecting the Results
Presentation of the ResultsConclusions and RecommendationsAbstract
Appendix
Where is the Innovation?
General Hints on How to Study.
Ver. 2.0. 14th Apr 2005.
7/29/2019 TechWriting Guidelines
4/75
M.S.Ramaiah School of Advanced StudiesVKBMDD 4
Introduction
Scope: Presentation ofbroad guidelines on writing a project report.
Purpose: Help thestudents who have to do lot of technical writing.Assignment Reports
Examinations
Project Reports
This talkattempts to help the students in good technical writing ,
specifically relating to Writing a Project Report.
Plan: General IssuesElements of Technical WritingTechnical
Report Writing.
7/29/2019 TechWriting Guidelines
5/75
M.S.Ramaiah School of Advanced StudiesVKBMDD 5
"Practice is the best of all instructors.
--Publilius Syrus,Syrian-born Roman author, c. 100 BC
7/29/2019 TechWriting Guidelines
6/75
M.S.Ramaiah School of Advanced StudiesVKBMDD 6
Purpose:
Provide an opportunity to develop the writing skills.
Assignment Convey the ability to analyze a problem.
Exam Ready to use knowledge plus ability to be precise
Project Report Physics of the problem and its application
Critical view - design/analysis process
Resultsconclusions
Oral and Written presentation.
7/29/2019 TechWriting Guidelines
7/75M.S.Ramaiah School of Advanced StudiesVKBMDD 7
Why Technical Writing?
Build on existing knowledge
Propagate the knowledge
Co-workers/Team members Sales/Marketing personnel
Customers
Technical Work is NOT Technical Writing
Commitment & Details
7/29/2019 TechWriting Guidelines
8/75M.S.Ramaiah School of Advanced StudiesVKB
MDD 8
Good Vs Bad writing: This is subjective.No one is perfect.
Technical writing is a specialized field that requires
Basic Requirements
PersonalDiscipline
Skill in Writing Clearly and Concisely
Understanding of Technical Products and Processes
Organization Skill
Knowledge of numerous software tools
7/29/2019 TechWriting Guidelines
9/75M.S.Ramaiah School of Advanced Studies
VKB
MDD 9
Organisation
What are you writing about?
What do you plan to achieve in what you are writing?
I II
IIIIV
Ideas
Flow
Hierarchy
Refinement
7/29/2019 TechWriting Guidelines
10/75M.S.Ramaiah School of Advanced Studies
VKB
MDD 10
Audience
Who is going to read the report?
What is the level of their current knowledge?
What background information to include?
Why is the reader reading the report?
Is the document supposed to inform or convince?
How much information is needed?
How much time does the reader have to read it?
7/29/2019 TechWriting Guidelines
11/75M.S.Ramaiah School of Advanced Studies
VKB
MDD 11
Example of an old Technical PaperFrom: Philosophical Transactions of the Royal Society 41, 162-66 (1739)
AnExperiment to prove, that Water, when agitated byFire, is inf ini tely
more elastic thanAir
in the same circumstances;by the late RevdJohnClayton, Dean ofKildare inIreland
SirThomas Proby having heard of a new Digester, which I contrived, had a Desire to
see it, and some experiments made therein. I had a small one which I designed
only for an inward Cylinder; this I could easily put in my Pocket: Wherefore ,
going to pay him a Visit at , but that the Vessel was very weak, and Ifeared would not endure the Pressure of so violent a Heat; yet something
desirous to have the Experiment tried; I said I was ready to venture my Vessel:
. into the Fire about half way; and in about three Minutes time I found it
raised to a great Heat; .. . Scare had I done speaking, and SirThomas
thereupon moved his Chair to avoid Danger; .. , it burst as a Musquet had
gone off. A Maid that was gone a milking, heard it considerable Distance; the
Servants said it shook the House. The Bottom .
(This old style of writing was uninhibited, personal and relaxed.)
7/29/2019 TechWriting Guidelines
12/75M.S.Ramaiah School of Advanced Studies
VKB
MDD 12
Example of a modern Technical Paper
From: Proceedings of the Royal Society 457, 1533-1554 (2001)
Decay of a three-dimensional vortex in an enclosure
By Name of the Author(s), Institution, Address, e-mailReceived 7 January 2000; revised 17 October 2000; accepted 6 December 2000
Abstract:..Keywords: vortex motion; viscous decay; closed streamlines; cavity; toroidal surface
___________________________________________________________________________________________
1.IntroductionAlthough many studies exist of both inviscid and viscous free vortices, not many exist
of confined three-dimensional vortex motions, despite these being of fundamental and
practical interest. Confined flows, of course, have special complications brought about
by, for instance, the presence of corner or secondary vortices and separation and
reattachment points; moreover if the initial state is turbulent, transition to the laminarstate will occur with the decay of the vortex motion. It is clear that with all these
complexity one will
(The modern style is more compact, terse, to the point and less personal.)
7/29/2019 TechWriting Guidelines
13/75M.S.Ramaiah School of Advanced Studies
VKB
MDD 13
Brevity is the soul of wit.
This report, by its very length, defends
itself against the risk of being read
Winston Churchill
WilliamShakespeare
"I'm sorry this letter is so long. I didn't havetime to write a shorter one."
Pascal
7/29/2019 TechWriting Guidelines
14/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 14
Conciseness
Fiction Technical
Information
Emotion
Mood
Image
Word Play
Information
In the interests of clarity, it seemed
necessary to constantly remind myself to
pay not the slightest attention to the
elegance of the presentation; I adhered
conscientiously to the rule of the brilliant
theoretician, Ludwig Boltzmann, to leave
elegance to tailors and shoemakers.
--Albert Einstein
Be Concise Be CompleteBUT
7/29/2019 TechWriting Guidelines
15/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 15
Basic Requirements
Good Vs Bad writing: This is subjective.No one is perfect.
writing should meet minimum acceptable standard.
Avoid spelling errors (like bad notes in music)
Use built-in Dictionary but dont rely wholly on it.
Following procedure followed for performing model analysis
There are too birds on the tree
Select appropriate version of English for spell checking
Load and boundary conditions applied on the model is shown in
the figure bellow
The following steps are used in preparing FE model for thermalanalysisodal analysis
Patiently search. Proof Read.
7/29/2019 TechWriting Guidelines
16/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 16
Some Guidelines regarding Flow: Use appropriate words. Avoid
verbose and bombastic language. Each sentence must have a main
verb (action). Usesimple declarative sentences. Let the sentences be
inter-connected. Each paragraph contains one main idea. Paragraphs
must be inter-connected. (Explain with 1,2,3 above as an example.)
Avoidgrammaticalerrors (like a bad tune)Study and practise.
Maintain a good flow of language. (like a good song)This comes
by practice. Write and re-write. Change the sequence of sentences.Write in several ways.Read loudly. Select what you feel as the best.
The operating speed of the impeller is 24000 rpm (revolutions per
minute) that is the exiting frequency of the impeller system is the
operating speed in per second. Hence the exciting frequency in
revolution per second is 4500 rps (Hz).
7/29/2019 TechWriting Guidelines
17/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 17
Use Simple declarative sentences.Note the irony:
He should be especially careful to shun the long, meandering sentence that is
crammed with obscurely related phrases and clauses, in which the subject and
predicate seem hopelessly to be searching for each other and the verb has a kind offloating object.
- from Dwight E Gray, So you have to write a technical report, ARP,
Washington, 1970. Ch.1, p.3.
Avoid phrases like:Coming to the point
It is important to note
All in all
To reiterate
It cant be overemphasized that We have to note especially that
Can I ask you a question?This itself is a question.
7/29/2019 TechWriting Guidelines
18/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 18
Some examples of bad usage:
Ex. 1: The number of tasks are (noun in singular, verb in plural)
Data: is it singular or plural?
Ex. 2: although the pressure was very high, it iswithin acceptable limits; (tensemismatch)
Ex. 3.I t was aim to studythe characteristics of the comparator responseThe aim was to study
Ex.4. It was also verified forits various building blocks were studied for their
designed values, which wassatisfactory for the output response. Too many verbs in a
single sentence. (sentence too long, too-many verbs with mixed number)
It was verified if
( a ) the building blocks meet the design specifications and
(b ) the output gives a satisfactory response.
7/29/2019 TechWriting Guidelines
19/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 19
If language is not correct, then what is said is not what is
meant. If what is said is not what is meant, then what
ought to be done remains undone.
--Kong Fu Zi/Confucius
7/29/2019 TechWriting Guidelines
20/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 20
Elements of Technical Writing
Purpose: Convey Information in clear, precise, un-ambiguous, and
technically sound language. Technical writing consists of technical terms.
Vocabulary of technical terms. A student of distinction scores becausehe/she uses technical terms precisely. Technical terms in Cricket:
Lindwall is having a fast run-up for his bowling.
He has one long-leg, one short-leg, one square-leg.
Maintain a Handbook for Glossary of Technical Terms. Whenever you
come across a new technical term, enter it with definition, example of
usage with Figure, symbol, unit, cross reference to related words.
Examples: Understand the subtle difference between similar technical terms.
sound, acoustic, vibration; ultra-sound, super-sonic.
Is this a valid question: What is the velocity of sound waves?time, duration, interval, delay;
Force, pressure, stress,
Strain, elongation, displacement, deformation, amplitude
7/29/2019 TechWriting Guidelines
21/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 21
Elements of Technical Writing
Vocabulary of technical terms (cont.)
Multi-dimensional Vs multi-channel
Factorization Vs Decomposition; The factors are Vs The components areAnalog Vs Continuous; Analog Vs Analogue; Discrete Vs Digital;
Convolution Vs Correlation
waveform of an amplifier is;
motor is reversed;
logarithmic bandwidth is this a valid technical term?
which keeps the residual echo minimum; - is this correct?
with certain assumptions on certain circumstances and constraints; (too vague)
Use the appropriate word based on the context.
50% of the learning/teaching effort goes towards building the technical vocabulary.
Knowledge of the technical terms must be available at finger tips. A students level of
confidence depends on this knowledge.
El t f T h i l W iti
7/29/2019 TechWriting Guidelines
22/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 22
Elements of Technical Writing
Use of Unit. What is the time? six twenty. 620. It makes sense.
what is the speed? 600. 600 what? 600 mph or 600 kmph or 600 rpm?
Always specify the Unit along with the number. Use appropriate unit based on thecontext. In place of 0.003 meter, use 3 mm for easy readability. But while solving
problems use appropriate unit. While entering data as input into a program, use the
appropriate unit. Units are always in singular (exception feet?). In case of Units
having proper names the first letter is capitalized (convention varies). Ex: Hz, dB.
Abbreviations for milli, kilo etc are always in lower case. Ex: kHz, 3 mm.
Sometimes a subtle distinction is made between meter-squared Vs sq-meter (area).
When a sequence of numbers is given, specify unit only ones: 100, 1000 and 4000 Hz
not 100 Hz, 1000 Hz and 4000 Hz. ( is the previous sentence correct?)
Dimension: Dimension of speed is the same (L/T) irrespective of the Unit. A
knowledge of Dimension helps in verifying the correctness of a formula.Which formula is correct: f=cl (?) or c = fl (?). f: frequency = 1/T. c = L/T. l = L.
El t f T h i l W iti
7/29/2019 TechWriting Guidelines
23/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 23
Elements of Technical Writing
Symbols and Mathematical Formulae:
Mathematics is the queen of science. It is a short hand notation.
Physical situation > Mathematical model > Solution > Interpretation in physical terms.(Give example here: Grand fathers age is the square of grand-sons age; 2*GF+GS=78.)
Define the symbol the very first time it is used. Use symbols consistently through out
the presentation. Ex: frequency is represented by the symbol f ( orn). Note the
difference between the angular frequency w (radians per sec) and the linear frequency
f (Hz).
Use appropriate symbols for Scalars, Vectors, Matrices. Define the convention.
Transforms are generally shown in Upper case. F(w), T(s), H(z).
Take care of sub-scripts and super-scripts. Use parenthesis to properly group theterms. Numerator and denominator are to be properly separated.
El t f T h i l W iti
7/29/2019 TechWriting Guidelines
24/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 24
Elements of Technical Writing
Tables: are used to show experimental data where ( a ) one or more of the variables is
non-mathematical or ( b ) there are too many variables or ( c ) the dependence
amongst the various variables is not obvious (no underlying theory)or ( d ) the data is too sparse.
Ex: Frequency of occurrence of different letters; Confusion matrices in listening tests;
Velocity of acoustic waves in different media.
Generalization cant be drawn from the results presented in a Table. Sometimes Bar
graphs, pie-charts are used to visualize data in a Table.Alphabet Frequency
e 20%
t 18%
s 12%
r 6%
Medium Velocity
air
clear-water
Sea-water
oil
El t f T h i l W iti
7/29/2019 TechWriting Guidelines
25/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 25
Elements of Technical Writing
Graphs: are used where the variables (a) take on numerical values and (b) are
grouped as dependent and independent. Example: Filter response. Independent
variable, frequency, is shown on x-axis. Dependent variable, gain, is shown on the y-
axis. Proper units and range must be chosen to illustrate the functionality. Use logscale when the range is very large. Ex: Frequency range over 10 to 100,000 Hz.
Sometimes a family of curves is shown. Filter response also depends on the order of
the filter. This is shown as a parameter. Throughout the experiment the value of the
parameter remains the same. Experimentally measured data are to be shown as
discrete points along with the fitted curve. The following graphs represent filterresponses of first order LPF and 2nd order HPF. What is wrong?
7/29/2019 TechWriting Guidelines
26/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 26
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
4 7 5 12 3 7 4 2 15 6 4 8 3 2 0 5 0
3 2 2 5 4 2 3 6 2 7 4 8 5 9 4 2 0
4 11 16 28 31 38 42 44 59 65 69 77 80 82 82 87 87
3 5 7 12 16 18 21 27 29 36 40 48 53 62 66 68 68
18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34
4 4 4 5 7 2 0 3 2 4 6 3 8 6 2 15 6
1 2 2 3 7 6 6 6 4 2 8 6 4 11 9 4 3
91 95 99 104 111 113 113 116 118 122 128 131 139 145 147 162 168
69 71 73 76 83 89 95 101 105 107 115 121 125 136 145 149 152
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50
3 0 9 12 3 3 5 6 8 6 9 10 6 8 11 7
5 3 7 4 8 0 2 7 12 15 5 9 7 12 15 15
171 171 180 192 195 198 203 209 217 223 232 242 248 256 267 274
157 160 167 171 179 179 181 188 200 215 220 229 236 248 263 278
Elements of Technical Writing
7/29/2019 TechWriting Guidelines
27/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 27
0
2
4
6
8
10
12
14
16
1 2 3 4 5 6 7 8 9 10 1 1 12 1 3 14 15 1 6 17 1 8 19 20 2 1 22 2 3 24 25 2 6 27 2 8 29 30 3 1 32 3 3 34 35 3 6 37 3 8 39 40 4 1 42 4 3 44 45 4 6 47 4 8 49 50
Elements of Technical Writing
7/29/2019 TechWriting Guidelines
28/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 28
0
50
100
150
200
250
300
0 10 20 30 40 50 60
Elements of Technical Writing
Elements of Technical Writing
7/29/2019 TechWriting Guidelines
29/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 29
Elements of Technical Writing
Chapters
Sections
Sub-Sections:
When the size of the document is long it is usually divided into Chapters, Sections and
sub-sections. There are standard ways for identifying these. Ch. I, II, or Ch. 1, Ch.2
; Sec. 1.1; Sub-Section: 1.1a, 1.1b etc or 1.1.1, 1.1.2 etc.
References:are the sources of information that were actually referred during the
preparation of the work. See Staff-Student Handbook for details.
Abstract:will be discussed later.
Title:will be discussed later.
Writing a Project Report
7/29/2019 TechWriting Guidelines
30/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 30
Writing a Project Report
Order of items as it appears / Size Order of items as it is written /Effort
Title & Title Page Introduction 30%
Table of Contents Body of the Report 30%List of Tables, Figures, Symbols Conclusions and Recommendations 10%
Abstract one page Appendixes, References 10%
Introduction 15% Table of Contents
Body of the Report 60% Abstract & Title 10%
Conclusions 10% Acknowledgement
Recommendations
Appendixes
References
IMRAD+C: Introduction - Materials and Methods (or Experimental details) -
Results and Discussion (Analysis in some journals) - Conclusions
(Conclusions and Recommendations)
Selecting a Project
7/29/2019 TechWriting Guidelines
31/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 31
Selecting a Project
Dont be too ambitious - selecting a big project that cant be handled within the
available time reflects badly(give examples) - Dont select a trivial project either
Discuss with various persons
What Employers look for in a project? Important Points to remember:
DEPTHQUALITYCOMPLETENESSKNOWLEDGE ACQUIRED
SKILLS ACQUIREDPRESENTATION SKILLS (Oral and Written)
Depth: Thoroughly familiar with all the terms / concepts /formulae used.
Quality: Work must show the ability to solve a problemknow the difference
between reality and model: Resistor Vs Resistance? (More about it later).
Completeness: Making a big claim in the Title of the project, but within the report
stating that due to lack of time only a part could be done - not a good practice.
Knowledge/Skills Acquired: Employers are going to test the knowledge relating to theproblem areaYou must become an expert in the chosen problem area (sub-area)
be able to teach /guide / lecture -
Composing the Title
7/29/2019 TechWriting Guidelines
32/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 32
Composing the Title
Wrong Titles for a Project:
Data Acquisition System, Image Processing, Digital Communication System, Network
Control System, Analysis of an IC Engine
More appropriate Title:
A high speed analog-to-digital converter based on
Human Face Verification for Security Clearance based on
An adaptive delta modulation system for speech
Software for delay reduction in Network traffic
Calculation of Stress induced in the casing of a four stroke engine based on simulation
studies
7/29/2019 TechWriting Guidelines
33/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 33
Abstract
7/29/2019 TechWriting Guidelines
34/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 34
Having an intellectual and affective artistic content
that depends solely on intrinsic form rather than onnarrative content or pictorial representation
A written summary of the key points especially of a scientific paper
Mini Version of the paper
Summary of a body of information in a paragraph
Condensed version of a longer piece of writing
that highlights the major points covered
ABSTRACT
7/29/2019 TechWriting Guidelines
35/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 35
ABSTRACT
Quickly and accurately identify basic contents of the paper
Check if the related research is of interest
Quickly acquaint the reader of current research
Generate interest and curiosity of the non-specialist reader
Entice potential readers into obtaining a copy of the full paper
To be remembered long after the paper has been read
Concise
Complete
To attract the interest and curiosity of the non-specialist reader
Because on-line search databases typically contain only abstracts
7/29/2019 TechWriting Guidelines
36/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 36
ABSTRACTDescriptive Informative
What Information is contained.
Purpose (Why?), Method (How?) and
scope (What?) of the
report/article/paper
Short, usually under 100 words.
Without results, conclusions, or
recommendations.
Organization not contents
Generates interest in the reader to go
and look up the results, conclusions
and recommendations in the paper
Communicate specific information
from the report, article, or paper
Include the purpose, methods, and
scope of the report, article, or paper
Provide the report, article, or
paper's results, conclusions, and
recommendations
Are short -- from a paragraph to a
page or two, depending upon the
length of the original work being
abstracted. Usually informative
abstracts are 10% or less of the
length of the original piece
Allow readers to decide whether
they want to read the report, article,
or paper.
7/29/2019 TechWriting Guidelines
37/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 37
Info rmative Abstract:
Cold weather tests were made to determine the effect of cold starting of the quantity of
fuel injected at cranking speed for two types of injection pump. The diesel engine of
the energy cell-Lanova type that was used had 3.75bore, 5 stroke and 331 cubic inchdisplacement. The cold room was maintained at -100 F ; engine, batteries, fuel and
lubricating oils, and all equipment were chilled to -100 F for at least 8 hours before the
engine was started. .
The Effect of Injection Pumps on Cold Starting of Diesel Engines.
Descr ipt ive Abstract:
Results are presented of a series of cold-room tests on a diesel engine to determine the
effect on starting time of (1) fuel quantity delivered at cranking speed, and (2) type of
fuel injection pump used. The tests were made at a temperature of -100 Fahrenheit;
engine and accessories were chilled to -100 F at least 8 hrs before the experiment
began.
ABSTRACT
7/29/2019 TechWriting Guidelines
38/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 38
ABSTRACT
Contents:
Problem Statement
Methodology
Results
Conclusions
What has been done?
How was it done?
What was found?
What do the findings mean?
What are the advantages?
How well it works?
Complete Covers the major parts of the project.
Concise Contains no excess wordiness or unnecessary information.
Clear Readable, well organized, and not too jargon-laden.
Cohesive Flows smoothly between the parts.
7/29/2019 TechWriting Guidelines
39/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 39
ABSTRACT
Structure:
Purpose of the study/paper: Primary objectives and scope of the studyReasons why the document was written
Rationale for your research.
Techniques/Approaches used: Experimental
Analysis
Sources.
Results/Collected Data/Observations:Experimental
Theoretical
New Findings/Contradictions
Accuracy/Reliability
Conclusions: Why are the results of this study important
How do they relate to the purpose?
Suggestions/Recommendations
7/29/2019 TechWriting Guidelines
40/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 40
ABSTRACT
Hints:
Reread the article, paper, or report with the goal of abstracting in mind
Write first draft (No Cheating)
Don't merely copy key sentences
Summarize information in a new way
Look at main parts of each section of the paper
Revise the rough draft
Improve Organization
Use the headings, outline heads, and table of contents as a guide
Improve Transitions
Drop Unnecessary Information Add Important Information
Eliminate wordiness
Check spelling, grammar and punctuation
7/29/2019 TechWriting Guidelines
41/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 41
ABSTRACT
Hints:
Clear and concise results/conclusions but adequate description of project
Assume good Technical vocabulary -- Avoid highly specialized words/abbs. Past tense to describe the work already done, Present tense for existing facts
Use primarily active voice. Use passive voice if it reduces word count
Proper word choice for conciseness
Drop unnecessary informationthis paper will look at.... , This Paper, is described/reported
It is believed that.,
Be Specific (-10F versus very low temperature)
Use Key words
Do not repeat or rephrase the title
Do not refer to things not in the paper
7/29/2019 TechWriting Guidelines
42/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 42
Introduction
Writing the Introduction
7/29/2019 TechWriting Guidelines
43/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 43
g
Introduction has three principal parts
A Scope and subject matter
Amplification of the TitleWhat the report is all aboutLimits of coverage
B Purpose, Audience
amplification of the preface if there is one - Purpose of the report not the purpose
of the experimentIs it a users manual, is it a technical report; what background
is assumed on the part of the readerwhat are the limits of the study -
C Plan of the work
amplification of the Contents - an overview of the reporthow things are
organized and why so
Length of the Introduction: 10 to 15%.
DONT: Start with a long history, very general discussion about the subject matter.
DO: Let the reader to know the subject matter of the report immediately.
Writing the Introduction
7/29/2019 TechWriting Guidelines
44/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 44
g
Example 1: Hindi Movies
Scope / Subject: Narrow down: Critical review of Hindi Movies;Critical review of Love stories in Hindi Movies; Critical review of
tri angular lovestories in Hindi Movies
Purpose / Audience:Reading material during travel - Entertainment
Written for Students of Social Science
Plan: selection criteriacase by case presentation - factors considered
for analysisconclusions
---------------------------------------------
How to expand? from one page to one chapter or even several chaptersthe above topic. See Next Slide.
7/29/2019 TechWriting Guidelines
45/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 45
Writing the Introduction
Example 1: Hindi Movies: Critical review of triangular love stories
After the broad introductionTypes of Hindi MoviesStatistics
Types of love storiesLove marriage Vs arranged marriage
Influence of religion, financial status, age factorare the stories
realistic? Do they reflect social valuesSpecialty about triangular
love storiesStatisticsPopularity
Purpose: can range from entertainment to a PhD thesis in sociology
Writing the Introduction
7/29/2019 TechWriting Guidelines
46/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 46
g
Example 2: Cricket Match
Scope / Subject: Critical review of cricket match; Critical review ofclose-finish matches ( one ball , one run, one wicket) (one-day
match or test match)
Purpose / Audience:Reading material during travel - Entertainment- or
written for serious fans
Plan: selection criteriacase by case presentation - analysis
conclusions
Writing the Introduction
7/29/2019 TechWriting Guidelines
47/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 47
Writing the Introduction
Wrong styles of Introduction
VLSI is an exciting and important area in electronics. Over the pastdecade it has emerged as
Security is a vital issue of national importance. Todays technology
has advanced
Instead, use direct approach:
This report presents in detail the VLSI design of a first order
Butterworth analog filter for audio applications.
A digital image processing algorithm is presented that verifies the
image of the human face recorded using a web camera againstimages stored in an existing database. The algorithm is based on
Body of the Report
7/29/2019 TechWriting Guidelines
48/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 48
y p
Answer the following questions:
What did you do? The Problem (one or two chapters)
How did you do it? The Method and the Tools (2 or 3 chapters)
What did you find out? Results (one chapter)
(Dont include conclusions and recommendations in the Body of the
Report)
Problem
7/29/2019 TechWriting Guidelines
49/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 49
Problem is broadly specified by the Programme Manager.
But narrow down the problem.
Ex: where do you live?In solar system, on earth, in India, in Karnataka,
Subject > Area > Topic > Problem (Area )> Your Problem (sub-area)
Electronics > Digital Signal Processing > Image Processing > Face Recognition
Face Recognition: Is it identification or Verification?
Technique: What Features are used? What is the Classification strategy?Situation: Input Image: Passport photographs, web camera, movie clippings etc.
Setting-up performance criteria is a part of the problem statementIs it to improve
the speed or accuracy?Is it hardware implementation or simulation study etc?
What is the size of database?
Relevance: Application.Why have you selected this problem? What are theengineering challenges that are addressed in the problem?
Literature Survey: How similar problems have been solved? Put your work in the
contemporary context.
Problem #2
7/29/2019 TechWriting Guidelines
50/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 50
State the Problem (PHYSICS/REALITY). Start from the broad area and narrow down
to the specifics.
Engineering design is a trade-off between Performance and Cost.
What are the performance criteria? What are the goals? What are the costs involved?
NARROW DOWN.
State the various approaches available to solve the problem. Literature Survey.
Justify the particular approach you are going to use.
Give both the theoretical basis and the basis for selecting particular tools.
If you are good at coding (programming), nothing like writing your own code.
Methodology and Tools
7/29/2019 TechWriting Guidelines
51/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 51
gy
Generally a software tool is available. Based on the problem proper software tool has
to be used. Proper input has to be specified. The tool also generates graphs.
What is the difference between a Technician and anEngineer?
A Technician knows how to use the tools. An Engineer can DESIGN a system. An
Engineer can solve a problem, meet the challenges of a new situation.
Master the tool, but know its pit falls
Some designs of automobiles, aircraft, computers have been withdrawn from themarket because of bad design. This situation arises due to improper use of tools.
Three examples of Pit Falls: a) The spectrum of a sine wave computed using the FFT
showed the spectrum of an exponentially damped resonance. b) Pole-zero
estimation was made while the input signal that was made-up of only poles.
c)Phase response showed a large range while theoretically it has to be within 2p.
WARNING: Understand clearly the Physics of the problem
and the limitations of the tool.
Collecting the Results
7/29/2019 TechWriting Guidelines
52/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 52
Validate using simplified models. Solve it analytically. Estimate the expected results
and compare them with those generated by the tools. Then apply to a complex
situation. Replicate an earlier study.
How are you going to test the results?
Generate test cases like a test dose of an injection for possible allergic reaction.
Validate the resultsCross check the results to ascertain that the tools are being used
properly, check if appropriate inputs have been given - in millimeter or meter,
Temperature in Degree F or C, proper polarity ( + or -) etc.
Run the Experiment for Repeatability, Consistency. One Single Run is no experiment.
No conclusion can be drawn.
Collect the Results in a systematic manner. Some of the experiments may be time
consuming. Proper planning is required.
Presentation of Results
7/29/2019 TechWriting Guidelines
53/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 53
How to present the results? Prepare a menu card. Serve item by item.
The presentation must cover the following:
1 Tools or equipments used. Model No., Version No. , Manufacturer or Developer.
Actual set-up. Additional details can be given in Appendix.
2 Testing of the tool on a smaller scale before the actual presentation of the results or
Calibration of the instruments used to make the measurements.3 Testing on data where results are predictable or replication - for validation.
4 Scope of the experiments regarding the range of the input parameters and what are
the output parameters that are being measured.
5 Present one experiment at a time with a clear objective for the experiment. Present
the results and discuss the main findings. Use Tables, Graphs etc for properillustration. Use proper scale and legend for the Graphs.
6 Show the link between one experiment and another. Present the results in a graded
manner.
Conclusions and Recommendations
7/29/2019 TechWriting Guidelines
54/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 54
Conclusions are convictions based on (experimental) evidence.
Results are measurements. What you infer from the results are the conclusions.
Exmp: Data on Rain fall Vs month of the year.
Conclusion: Usually there is no rain fall in Bangalore during the month of March.
Recommendations: Suggested action. Dos and Donts.
Exmp: Conclusion: Delayed Submission of Assignment.
Recommendation: Deduction of marks.
List the Conclusions. For each item in the list provide the supporting evidence byreferring to the Figures or Tables in the main body of the report.
Problem Formulation: begins with reality or Physics of the process - Modeling
(theory).
Experiments are conducted using the model. Why? To deal with a wide range of input
parameters, situations etc. Working with real systems is time consuming,expensive.
Results are generated using simulation tools or experimental setups.
Conclusions take us back to the reality or physics of a process.
Appendix
7/29/2019 TechWriting Guidelines
55/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 55
Explanatory material that would interfere with the logical continuity.
Avoids congestion of the report. Pertinent but too detailedto be seenlater if required
Not directly contributing to the reportnot that of the author -
Supporting material not critical and may be of interest only to a few
readers.-----------
Supplementary calculations; detailed derivations; charts, maps, graphs
as additional information; detailed experimental results; description
of equipment; description of software tool;-----------
Each item has to have an identifying tag and a title.
Where is the innovation?
7/29/2019 TechWriting Guidelines
56/75
M.S.Ramaiah School of Advanced StudiesVKB
MDD 56
How can a student bring-in an innovation into his/her project work?
In the selection of the problem.
In the methodology used to solve the problem.
In the presentation of results and ability to draw interesting
conclusions.In visualizing new applications.
In the presentation of the report.
General Hints
7/29/2019 TechWriting Guidelines
57/75
M.S.Ramaiah School of Advanced Studies
VKB
MDD 57
Whole to Part: Going from broad area or overview into details is a better
approach. Master Plan to fine details. (Four walls and a roof; later interiors)
Do the work in several rounds. First round: Assume that you are preparing one
page assignment to be submitted within one day. Propose a tentative title, write a
crude report. Second round add some more details etc.
Look for information sources. Prioritize: Text Books, Journals (review articles)and Web browsing. Write down the reference immediately. Be FOCUSSED while
browsing. Dont go too deep during the first round of reading. Dont try to
understand all aspects. Just establish links between the problem and the sources.
Several rounds of light reading is better than one round of deep reading.
Categorize the reading material: Definition, Concept, Illustration, Formula,
Details, Case Study etc. Xerox parts and build-up a crude report. Then write it in
your own words.
R f i
7/29/2019 TechWriting Guidelines
58/75
M.S.Ramaiah School of Advanced Studies
VKB
MDD 58
Referencing
Harvard Reference
Oxford Reference
APA Reference
All statements, opinions, conclusions etc. taken from another
writers work should be cited, whether the work is directly quoted,
paraphrased or summarized.
A restatement of a
text or passage in
another form or
other words, often
to clarify meaning.
Presenting the
substance in a
condensed
form; concise
Harvard Reference
7/29/2019 TechWriting Guidelines
59/75
M.S.Ramaiah School of Advanced Studies
VKB
MDD 59
Harvard Reference
There are indications that passive smoking is potentially threatening to
the health.......... ( Ln1 and Ln2, Yr; Ln, Yr)
In the book by Ln1 and Ln2 / Ln1 et al. (1995) .....
Ln1 and Ln2 (Yr) state that "networking is no longer solely
within the male domain . . ."(p.XX).
Ln1 and Ln2 (Yr) in discussing staff development state that:
"Development is infectious, and staff who previously have recoiled
from undertaking a degree or conversion course have been encouraged
by the success of others"(p.XX).
In the Harvard System cited publications are referred to in the text by
giving the authors surname and the year of publication and are listed
in a bibliography at the end of the text.
Harvard Reference
7/29/2019 TechWriting Guidelines
60/75
M.S.Ramaiah School of Advanced Studies
VKB
MDD 60
Ln,Fn / Ln,Fn and Ln,Fn /Ln,Fn et al. (Yr) Title of the book, Edition,
Place of publication, Publisher.
Harvard Reference
Ln, Fn (Yr) Chapter Title.In: Fi. Ln et al. (eds) Title of the book.
Place of publication, Publisher. p. xx- yy.
Ln, Fi. (Yr) Article Title.Journal Title, V(N), XX-YY.
Ln,Fn / Ln,Fn and Ln,Fn /Ln,Fn et al. (eds) (Yr) Title of the book,Edition, Place of publication, Publisher.
Book
Edited Book
Chapter in a Book
Article in a journal
In the Harvard System, the references are listed in
alphabetical order of authors names.
Harvard Reference
7/29/2019 TechWriting Guidelines
61/75
M.S.Ramaiah School of Advanced Studies
VKB
MDD 61
Harvard Reference
Ln1, Fi. et al(Yr)Article Title:Proceedings of the Conference held at
the Location. Place
Ln, Fn. (1998) Article Title. In: Ln, Fi. et al. Proceeding Title:Conference held at the Conference Location. Place. p.XX - YY.
Ln, Fn (1995)Dissertation title. Unpublished Degree dissertation,
University.
From published conference proceedings
From published conference proceedings
Dissertation
Harvard Reference
7/29/2019 TechWriting Guidelines
62/75
M.S.Ramaiah School of Advanced Studies
VKB
MDD 62
Oxford System
Sequential:
In this system each citation is given a unique number in the order in
which it appears in the text, either in brackets or superscripted.
Harvard Reference
http://home.ched.coventry.ac.uk/caw/harvard/index.htm
*
Electronic References
http://localhost/var/www/apps/conversion/tmp/scratch_3/CAW%20Harvard%20Reference%20Style%20Resources.htmhttp://localhost/var/www/apps/conversion/tmp/scratch_3/CAW%20Harvard%20Reference%20Style%20Resources.htm7/29/2019 TechWriting Guidelines
63/75
M.S.Ramaiah School of Advanced Studies
VKB
MDD 63
Electronic References
Ln, Fi. Mi. (Pub. Date). Title. Site. URL (Date Accessed).
WWW
Ln, Fi. (Msg. date) subject Line Discussion or Newsgroup list. List
address (Date Accessed).
Ln, Fi. Title. (1993). In Title of complete work.
Online resource. Path to the source (Date Accessed).
Online Reference Source
Ln, Fi. Title. (1993). Title of complete work Version No.
Name of the DB, Online resource. Access Info. (Date Accessed).
Electronic Publication/Database
Resources
7/29/2019 TechWriting Guidelines
64/75
M.S.Ramaiah School of Advanced Studies
VKB
MDD 64
Oxford English Dictionary http://dictionary.oed.com/entrance.dtl
(for subscribers only)
Merriam Webster http://www.m-w.com/netdict.htm(Dictionary and Thesaurus)
Rogets (Dictionary/Thesaurus/language Ref./Other Language ..)
http://thesaurus.reference.com/
William Strunks Element of Style http://www.bartleby.com/141/
Writing Guidelines for Engineering and Science Students
http://writing.eng.vt.edu
Purdue Online Writing Lab (OWL) Site Map
http://owl.english.purdue.edu/sitemap.html
Grammar Handbook
http://www.english.uiuc.edu/cws/wworkshop/grammar_handbook.htm
7/29/2019 TechWriting Guidelines
65/75
M.S.Ramaiah School of Advanced Studies
VKB
MDD 65
Put it before them briefly so they will read it,clearly so they will appreciate it,
picturesquely so they will remember it, and
above all, accurately so they will be guided byits light.
-- Joseph Pulitzer
Philosophy
7/29/2019 TechWriting Guidelines
66/75
M.S.Ramaiah School of Advanced Studies
VKB
MDD 66
Honesty is the best policy.
You cannot write a good report / paper unless you have something to say.
First decide what is that you want to say. Then say it boldly, clearlyand briefly.
Technical writing is a bor ingjob. Doing an experiment or computation or
observing the sky is more exciting. (They involve new tasks!) But technical
reporting is an equally important job. Hence it has to be done properly. It does
not necessarily mean we have to spend more time.
Philosophy
Poor technical writing makes one suspect about the care taken in your
technical work itself.
EXAMPLE for the TITLE
7/29/2019 TechWriting Guidelines
67/75
M.S.Ramaiah School of Advanced Studies
VKB
MDD 67
Floods
Floods in the Kaveri Basin
Floods in the Kaveri Basin during the Years 19902005
A Detailed Fluid Mechanical Study of Floods in the Kaveri Basin
during the Years 1990 - 2005 and Suggestions for their control
A Fluid Mechanical Study of Floods in the Kaveri Basin during
the Years 1990 - 2005 and Suggestions for their control
A Study of Floods and their control in the Kaveri Basin during
the Years 19902005
A Study of Floods and their control in the Kaveri Basin
EXAMPLES
7/29/2019 TechWriting Guidelines
68/75
M.S.Ramaiah School of Advanced Studies
VKB
MDD 68
From: The Origin of the Species by Charles Darwin (1859)
Page 352. Thus, on the theory of descent with modification, the
main facts with respect to the mutual affinities of the extinct forms
of life to each other and to living forms, are explained in a
satisfactory manner. And they are wholly inexplicable on any other
view.Notice the confident summary from a Master. Also notice the
word whollyin the last sentence: How precise and guarded he
is!
EXAMPLES
7/29/2019 TechWriting Guidelines
69/75
M.S.Ramaiah School of Advanced Studies
VKB
MDD 69
EXAMPLES
From: The Origin of the Species by Charles Darwin (1859)
Page 477. Although I am fully convinced of the truth of the views
given in this volume . I by no means expect to convince
experienced naturalists whose minds are stocked with multiple of
facts all viewed, during a long course of years, from a point of viewdirectly opposite of mine. It is easy to hide our ignorance under such
expressions as the plan of creation unity of design, &c., and to
think that we give an explanation when we only re-state a fact.
Feel the pressure and pain under which he is writing. Also notice
how he has used the word stocked. (Is it complimentary?) Howclearly he points out the mistake of other naturalists.
EXAMPLES
7/29/2019 TechWriting Guidelines
70/75
M.S.Ramaiah School of Advanced Studies
VKB
MDD 70
CURRENT SCIENCE Volume 88 10 April 2005
______________________________________________________________________________________________________________________________________________________
Dark energy: The cosmological challenge of the millennium
Authors:
Abstract: Recent cosmological observations suggest that nearly seventy per cent of
the energy density in the universe is unclustered and has negative pressure. Several
conceptual issues related to the modelling of this component (dark energy), which isdriving an accelerated expansion of the universe, are reviewed with special emphasis
on the cosmological constant as the possible choice for the dark energy.
EXAMPLES
7/29/2019 TechWriting Guidelines
71/75
M.S.Ramaiah School of Advanced Studies
VKB
MDD 71
CURRENT SCIENCE Volume 88 10 May 2005
______________________________________________________________________________________________________________________________________________________
Monsoon predictionWhy yet another failure?Authors:
Abstract: The country experienced a deficit of 13% in the summer monsoon of
2004. As in 2002, this deficit was not predicted either by the operational empirical
models at India Meteorological Department (IMD) or by the dynamical models at
national and international centres. Our analysis of the predictions generated by theoperational models at IMD from 1932 onwards suggests that the forecast skill has
not improved over the seven decades despite continued changes in the operational
models. Clearly, new approaches need to be explored with empirical models. The
simulation of year-to-year variation of the monsoon is still a challenging problem
for models of the atmosphere as well as the coupled oceanatmosphere system. We
expect dynamical models to generate better prediction only after this problem issuccessfully addressed.
EXAMPLES
7/29/2019 TechWriting Guidelines
72/75
M.S.Ramaiah School of Advanced Studies
VKB
MDD 72
CURRENT SCIENCE Volume 88 10 April 2005
______________________________________________________________________________________________________________________________________________________
Cratering and spall simulation of Pokhran-1 event with three-
dimensional transient finite element analysis
Abstract: Three-dimensional transient numerical simulation of coupled gas cavity and geological
medium problem resulting from underground nuclear explosion events is complex due to the gas
cavity growth, resulting into the large deformations and large strains of the geological medium and
shock-induced high strain-rate dependence of the response. However, it is important to establish
the effects of local inelastic and nonlinear behaviour due to crushing and cracking of the geological
medium, on the shock-waves near the source and the seismic signals beyond the elastic radius. This
study also helps simulate the shock-wave reflection effects from the free surface near the ground
zero, mound growth, spall near the free surface and the subsequent free fall of the mound due to
gravity effect resulting in crater formation. The impacting spalled rock layers give rise to
secondary seismic signals in addition to the primary signals that are observed in the near field
which in turn are known to influence the far-field seismic signals. The present article describes the
capabilities of a three-dimensional transient finite element code, SHOCK-3D, for the shorttimecavity growth, shock-wave propagation, mound growth and its free fall along with the settlement of
the mound observed after a longer duration for the composite layer medium. The code predictions
are benchmarked for the near-source experimental observations of the first Indian nuclear
explosion event of 1974, carried out at the Pokhran test site.
EXAMPLES
7/29/2019 TechWriting Guidelines
73/75
M.S.Ramaiah School of Advanced Studies
VKB
MDD 73
CURRENT SCIENCE Volume 88 Number 7 10 April 2005EDITORIAL
________________________________________________________________________________________________________________________________________________________________
Women, Science and the X-Chromosome
International Womens Day is celebrated every year on 8th March. The day has
been institutionalized by the United Nations, although various dates in March
have been previously associated with the struggle for equality of women. The
womens rights movement has its origins in the struggle to vote by women in the
United States in the latter half of the 19th century, most dramatically highlighted
by the 1873 trial of Susan B. Anthony in the United States for illegal voting,
Womens Day appears to have firmly rooted beginnings in Europe. March 8
presumably commemorates the famous strike in St. Petersburg organized by
Russian women in 1917, a spontaneous uprising forbread andpeace in a Russia
ravaged by war and ripe for revolution. Today, Womens Day is used to focusattention on the many issues that ensure that women continue to live in an
unequal world. This year, I received an invitation P. Balaram
Best Wishes
7/29/2019 TechWriting Guidelines
74/75
M.S.Ramaiah School of Advanced Studies
VKB
MDD 74
We will be glad to help you any time.
Be Professionals. Become Professionals.
Derive satisfaction from your work.Enjoy doing your work.
Money/wealth automatically follows you
if you are good professionals.
Wish you all an enjoyable stay.
Wish you all a stimulating educational programme.
Wish you all an excellent future.
H W i i
7/29/2019 TechWriting Guidelines
75/75
Happy Writing
Happy Reading