Technical writing: Some guidelines

Never forget Abbreviations No plagiarism Document elements Punctuation Examples of style Citations Bibliography

Technical Writing:Some Guidelines

Dr V N KrishnachandranProfessor of Computer Applications

Vidya Academy of Science & TechnologyThalakkottukara, Thrissur - 680 501

Dr V N Krishnachandran

Technical Writing: Some Guidelines


A talk delivered tofirst semester M Tech students of

Vidya Academy of Science & Technologyon 27 July 2015

as part of aBridge Course for M Tech studentsof Kerala Technological University




Acknowledgment

The content of these slides are based on thedocuments cited in the Bibliography.




Basic reference for style

Cover page of the 16th edition of The Chicago Manual of Style, one ofthe most widely used and respected style guides in the United States

(first published in 1906, now a classic with 1045 pages).




Outline

1 Never forget these universal aspects

2 Abbreviations

3 No plagiarism

4 Document elements

5 Punctuation

6 Examples of style

7 Citations

8 Bibliography




Never forget these universalaspects




Never forget: Spelling

Spelling mistakes are totally unacceptable.




Never forget: Spelling, grammar

Write in an active voice in the third person

Correct spelling

Correct grammar




Never forget: Figures

Neatly drawn diagrams

Use software to draw diagrams

Number the figures

Give a title to each figure

Include a List of Figures




Never forget: Tables

Neatly drawn tables

Number the tables

Give a title to each table

Include a List of Tables




Abbreviations




Abbreviations

Define acronyms or abbreviations prior to usingthem.

Example:The National Aeronautics and SpaceAdministration (NASA) was founded in 1958

Include a List of Abbreviation in alphabeticalorder.




Abbreviations

Use periods with abbreviations that end in alowercase letter.

Example:p., vol., e.g., i.e., etc., a.k.a., a.m., p.m., Ms.,Dr., et al.

Use no periods with abbreviations that appear infull capitals.

Example:VP, CEO, MA, MD, PhD, US




Abbreviations

No space is left between the letters of initialismsand acronyms, whether lowercase or in capitals.

The following abbreviations may precede a fullname: Assoc. Prof., Asst. Prof., Atty. Gen.,Pres., Prof., Sr. (sister).

Omit periods in abbreviations of academicdegrees.




No plagiarism




No plagiarism

(Image courtesy: http://www.bhprsd.org/Page/916)




No plagiarism

(Image courtesy:http://youthvoices.net/discussion/why-do-kids-plagiarize)




No plagiarism

When copy-pasting, always cite thesource.




No plagiarism

Any information in a document that is directlyquoted or copied from a source must be properlycited.

Any information in the report that is directlyderived or paraphrased from a source must beproperly cited.




No plagiarism

Example: Improper citationAnton, Bivens and Davis, Calculus, John Wiley andSons.[See: KTU Syllabus for I & II Semester BTechDegree (as on 01.07.2015), MA 101 Calculus]

Example: Proper citationHoward Anton, Irl C. Bivens, Stephen Davis,Calculus, 10th Edition, John Wiley and Sons, 2012.




No plagiarism

Any material derived from the web must comefrom credible and documentable sources.

Wikipedia is NOT a credible reference.




Document elements




Document elements: Front matter

Title page

Dedication

Table of Contents

List of Illustrations

List of Tables

Foreword

Preface

Acknowledgments

Introduction (if not part of text)

List of Abbreviations




Document elements: Back matter

Appendix(es)

Notes

Glossary

Bibliography or References

Index(es)




Document elements: Pagination

Lowercase roman numerals for front matter

Arabic numbers for text and back matter




Document elements: Title page

The title page gives:

the title of the report

the authors’ names and ID numbers

course name and number, department,institution

date of submission.




Document elements: Title page

Title should indicate exactly what the report isabout.

ExampleBridge Analysisvs.Analysis of a Pre-stressed Concrete Bridge




Document elements: Summary

The summary section/chapter:

states the topic of the report

outlines your approach to the task if applicable

gives most important findings, or key aspects ofdesign

states the main outcomes or conclusions.




Document elements: Summary

The summary section/chapter does NOT:

provide general background information

explain why you are doing the research,investigation or design

refer to later diagrams or references.




Document elements: Introduction

The introduction section/chapter includes:

the background to the topic of your report

a clear statement of the purpose of the report(for example, to present the results of yourresearch, investigation, or design)

a clear statement of the aims of the project

technical background necessary to understandthe report (for example, theory or assumptions)

a brief outline of the structure of the report ifappropriate.




Document elements: Conclusions

The conclusions part sums up the essential featuresof your work. This section

states whether you have achieved your aims

gives a brief summary of the key findings orinformation in your report

highlights the major outcomes of yourinvestigation and their significance.




Punctuation




Punctuation

(Image courtesy: www.proofreadersproofreader.com/




Punctuation: One space rule

One space should be used between twosentences – whether the first ends in a period, aquestion mark, an exclamation point, or aclosing quotation mark or parenthesis.

One space should follow a colon.




Punctuation: Quotation marks

Periods and commas precede closing quotationmarks, whether double or single.Examples:Correct: He said: “Tomorrow is a holiday.”Incorrect: He said: “Tomorrow is a holiday”.

Colons and semicolons follow closing quotationmarks.




Punctuation: Periods

If the ellipsis (that is, . . . ) is at the end of asentence, do not a full stop after it.




Punctuation: Vertical list

The following conventions are suggested:

A vertical list is to be introduced by a completesentence followed by a colon.

Items carry no closing punctuation unless theyconsist of complete sentences.

Can have any number of items

Choose a numbering scheme and be consistent

Example: Study this slide.




Examples of style




Examples of style

(Image courtesy: http://thinkbigdigitalmarketing.com/

keeping-nap-consistency-top-priority/)




Examples of style: Inconsistency

The contents page of a draft document before corrections(continued in the next slide)




Examples of style: Inconsistency

The contents page of a draft document before corrections




Examples of style: Titles

In chapter, section, etc. titles

All capitals (not favoured)Example: THE CHICAGO MANUAL OF STYLE

Initial capitals (IEEE style, see next slide)Example: The Chicago Manual of Style

First letter only capitalized (sentence case)Example: The Chicago manual of style




Examples of style: Titles

In titles, do capitalize:

Nouns (man, bus, book)

Adjectives (angry, lovely, small)

Verbs (run, eat, sleep)

Adverbs (slowly, quickly, quietly)

Pronouns (he, she, it)

Subordinating conjunctions (as, because, that)




Examples of style

In titles, do not capitalize:

Articles: a, an, the

Coordinating conjunctions: and, but, or, for,nor, etc.

Prepositions: on, at, to, from, by, etc.




Examples of style: Capitalization

Avoid unnecessary capitalizations





Correct usageVAST is an engineering college in Kerala state. Thecollege offers B Tech programmes in six branches,namely, civil engineering, production engineering,etc.

Incorrect usageVAST is an Engineering College in Kerala State.The College offers B Tech programmes in sixbranches, namely, Civil Engineering, ProductionEngineering, etc.





Capitalize the first word of every sentence

Capitalize proper nouns that specifically name aperson, place or thing

Capitalize the proper names of nationalities,peoples, races

Capitalize official job titles when used as part ofa name

Capitalize the full name of official programs,projects or plans. Always lowercase program,project or plan when the word stands alone.




Citations




Citations

IEEE Citation Style

The author name is first name (or initial) and last.

The title of an article (or chapter, conferencepaper, etc.) is in quotation marks.

The title of the journal or book is in italics.

The references should be numbered and appear in theorder they appear in the text.




Citations: Books

Books

J. K. Author, “Title of chapter in the book,” inTitle of His Published Book, xth ed. City ofPublisher, Country if not USA: Abbrev. ofPublisher, year, ch. x, sec. x, pp. xxx-xxx.




Citations: Conference Technical Articles

Basic format

J. K. Author, “Title of paper,” in UnabbreviatedName of Conf., City of Conf., Abbrev. State (ifgiven), year, pp. xxx-xxx.





For an electronic conference article when there areno page numbers

J. K. Author [two authors: J. K. Author and A. N.Writer ] [three or more authors: J. K. Author et al.],“Title of Article,” in [Title of Conf. Record as ],[copyright year] [IEEE or applicable copyright holderof the Conference Record]. doi: [DOI number]





For an unpublished paper presented at a conference

J. K. Author, “Title of paper,” presented at theUnabbrev. Name of Conf., City of Conf., Abbrev.State, year.




Citations: Electronic Sources

Basic format

J. K. Author. (year, month day). Title (edition)[Online]. Available: http://www.(URL)




Bibliography




Bibliography

1 The Chicago manual of style, 16th ed., The University ofChicago Press, 2010.

2 Philip Rubens (editor), Science and Technical Writing: AManual of Style, 2nd ed., Routledge, New York, 2002.

3 Leah M. Akins and Jefferson H Akins, (January 2009),“Technical Report Writing Guidelines,” [Online]. Available:http://www8.sunydutchess.edu/ faculty/akins/

documents/ TechnicalReportWritingGuidelines.pdf

4 “IEEE Citation Reference,” [Online]. Available: http://

www.ieee.org/ documents/ieeecitationref.pdf

5 “Preparation of Papers for IEEE TRANSACTIONS andJOURNALS,” (April 2013), [Online]. Available: https://

www.ieee.org/documents/transactions journals.pdf




Thanks . . .



Education

Technical writing: Some guidelines