Guidelines for Technical Writing

1. Guidelines for Technical Writing Vinod K. Banthia M.D.Deshpande

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.

3. Contents Introduction General Issues Basic Requirements Elements of Technical Writing Writing a Project Report Selecting a Project – Composing the Title - Writing the Introduction – Body of the Report – Problem – Methodology and Tools – Collecting the Results – Presentation of the Results – Conclusions and Recommendations – Abstract – Appendix Where is the Innovation? General Hints on How to Study. Ver. 2.0. 14th Apr 2005.

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 talk attempts to help the students in good technical writing , specifically relating to ‘Writing a Project Report’. Plan: General Issues – Elements of Technical Writing – Technical Report Writing.

5. "Practice is the best of all instructors.“ -- Publilius Syrus, Syrian-born Roman author, c. 100 BC

6. Purpose: Provide an opportunity to develop the writing skills. AssignmentConvey the ability to analyze a problem. Exam Ready to use knowledge plus ability to be precise ProjectReport Physics of the problem and its application – Critical view - design/analysis process Results – conclusions Oral and Written presentation.

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

8. Basic Requirements Technical writing is a specialized field that requires PersonalDiscipline Organization Skill Skill in Writing Clearly and Concisely Understanding of Technical Products and Processes Knowledge of numerous software tools Good Vs Bad writing: This is subjective. No one is perfect.

9. Organisation What are you writing about? What do you plan to achieve in what you are writing? Ideas I II Flow Hierarchy III IV Refinement

10. Audience Who is going to read the report? What is the level of their current knowledge? How much information is needed? What background information to include? Why is the reader reading the report? Is the document supposed to inform or convince? How much time does the reader have to read it?

11. Example of an old Technical Paper From: Philosophical Transactions of the Royal Society 41, 162-66 (1739) An Experiment to prove, that Water, when agitated by Fire, is infinitely more elastic than Air in the same circumstances; by the late Revd John Clayton, Dean of Kildare in Ireland Sir Thomas 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 I feared 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 Sir Thomas 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.)

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-mail • Received 7 January 2000; revised 17 October 2000; accepted 6 December 2000 • Abstract: ………………….. • Keywords: vortex motion; viscous decay; closed streamlines; cavity; toroidal surface • ___________________________________________________________________________________________ • Introduction • Although 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 laminar state 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.)

13. Brevity is the soul of wit. WilliamShakespeare “This report, by its very length, defends itself against the risk of being read” Winston Churchill "I'm sorry this letter is so long. I didn't have time to write a shorter one." Pascal

14. Conciseness Fiction Technical Information Information Emotion “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 Mood Image Word Play Be Complete Be Concise BUT

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) “Load and boundary conditions applied on the model is shown in the figure bellow” “The following steps are used in preparing FE model for thermal analysisodal analysis” Use built-in Dictionary but don’t 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 Patiently search. Proof Read.

16. Avoidgrammaticalerrors (like a bad tune) – Study and practise. “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)”. 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. Some Guidelines regarding Flow: Use appropriate words. Avoid verbose and bombastic language. Each sentence must have a main verb (action). Use simple 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.)

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 of floating 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 can’t be overemphasized that … We have to note especially that … Can I ask you a question? – This itself is a question.

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 is within acceptable limits’; (tense mismatch) Ex. 3.It was aim to study the characteristics of the comparator response… The aim was to study … Ex.4. “It was also verified for it’s various building blocks were studied for their designed values, which was satisfactory 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.

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

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 because he/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

21. Elements of Technical Writing Vocabulary of technical terms (cont.) Multi-dimensional Vs multi-channel Factorization Vs Decomposition; ‘The factors are…’ Vs ‘The components are…’ Analog 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 student’s level of confidence depends on this knowledge.

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 the context. 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.

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 father’s age is the square of grand-son’s 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’ ( or n). 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 the terms. Numerator and denominator are to be properly separated.

24. Alphabet Medium Frequency Velocity 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 can’t be drawn from the results presented in a Table. Sometimes Bar graphs, pie-charts are used to visualize data in a Table. e air 20% clear-water t 18% s Sea-water 12% r oil 6%

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 ‘log’ scale 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 filter responses of first order LPF and 2nd order HPF. What is wrong?

26. Elements of Technical Writing

27. Elements of Technical Writing

28. Elements of Technical Writing

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.

30. Writing a Project Report Order of items as it appears / SizeOrder 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”)

31. Selecting a Project Don’t be too ambitious - selecting a big project that can’t be handled within the available time reflects badly – (give examples) - Don’t select a trivial project either – Discuss with various persons – What Employers look for in a project? Important Points to remember: DEPTH – QUALITY – COMPLETENESS – KNOWLEDGE ACQUIRED – SKILLS ACQUIRED – PRESENTATION SKILLS (Oral and Written) Depth: Thoroughly familiar with all the terms / concepts /formulae used. Quality: Work must show the ability to solve a problem – know 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 the problem area – You must become an expert in the chosen problem area (sub-area) – be able to teach /guide / lecture -

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

33. Abstract

34. ABSTRACT Difficult to understand Not applied or practical Apart from concrete Thought of or stated without reference to a specific instance Having an intellectual and affective artistic content that depends solely on intrinsic form rather than on narrative 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

35. ABSTRACT • Quickly and accurately identify basic contents of the paper • Check if the related research is of interest • To attract the interest and curiosity of the non-specialist reader • 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 • Because on-line search databases typically contain only abstracts Concise Complete

36. ABSTRACT Informative Descriptive • 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. • 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

37. ABSTRACT The Effect of Injection Pumps on Cold Starting of Diesel Engines. Descriptive 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. Informative 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.75”bore, 5” stroke and 331 cubic inch displacement. 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. ….

38. ABSTRACT Contents: • Problem Statement • What has been done? • How was it done? • Methodology • Results • What was found? • Conclusions • 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.

39. ABSTRACT Structure: Purpose of the study/paper: Primary objectives and scope of the study Reasons 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

40. ABSTRACT Hints: • Reread the article, paper, or report with the goal of abstracting in mind • Look at main parts of each section of the paper • Use the headings, outline heads, and table of contents as a guide • Write first draft (No Cheating) • Don't merely copy key sentences • Summarize information in a new way • Revise the rough draft • Improve Organization • Improve Transitions • Drop Unnecessary Information • Add Important Information • Eliminate wordiness • Check spelling, grammar and punctuation

41. ABSTRACT Hints: • Clear and concise results/conclusions but adequate description of project • Proper word choice for conciseness • Use Key words • Be Specific (-10° F versus ‘very low temperature’) • Drop unnecessary information • “this paper will look at....” , “This Paper…”, “…is described/reported” • “It is believed that….”, • Do not repeat or rephrase the title • Do not refer to things not in the paper • 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

42. Introduction

43. Writing the Introduction Introduction has three principal parts A Scope and subject matter Amplification of the Title – What the report is all about – Limits of coverage B Purpose, Audience amplification of the preface if there is one - Purpose of the report not the purpose of the experiment – Is it a user’s manual, is it a technical report; what background is assumed on the part of the reader – what are the limits of the study - C Plan of the work amplification of the Contents - an overview of the report – how things are organized and why so – Length of the Introduction: 10 to 15%. DON’T: 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.

44. Writing the Introduction Example 1: Hindi Movies Scope / Subject: Narrow down: Critical review of Hindi Movies; Critical review of Love stories in Hindi Movies; Critical review of triangular love stories in Hindi Movies Purpose / Audience:Reading material during travel - Entertainment – Written for Students of Social Science Plan: selection criteria – case by case presentation - factors considered for analysis – conclusions   --------------------------------------------- How to expand? from one page to one chapter or even several chapters the above topic. See Next Slide.

45. Writing the Introduction Example 1: Hindi Movies: ‘Critical review of triangular love stories’ After the broad introduction – Types of Hindi Movies – Statistics – Types of love stories – Love marriage Vs arranged marriage – Influence of religion, financial status, age factor – are the stories realistic? Do they reflect social values – Specialty about triangular love stories – Statistics – Popularity –  Purpose: can range from entertainment to a PhD thesis in sociology 

46. Writing the Introduction Example 2: Cricket Match Scope / Subject: Critical review of cricket match; Critical review of close-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 criteria – case by case presentation - analysis – conclusions

47. Writing the Introduction Wrong styles of Introduction “VLSI is an exciting and important area in electronics. Over the past decade it has emerged as …”    “Security is a vital issue of national importance. Today’s 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 against images stored in an existing database. The algorithm is based on …”

48. Body of the Report 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) (Don’t include conclusions and recommendations in the Body of the Report)

49. Problem 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 statement – Is 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 the engineering challenges that are addressed in the problem? Literature Survey: How similar problems have been solved? Put your work in the contemporary context.

50. Problem #2 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.