Transcription
AcknowledgmentCOS 301Programming LanguagesTechnical Writing These notes are partially based on slides prepared byJosh Murphy, PhD candidate at the University ofMaine, presented to students in COS 301Programming Languages Fall 2007 and Fall 2008 Some examples used herein are used with permissionfrom some of my students in Fall 2008AudienceAudience for COS 301 Whenever you are writing, you are writing “for”someone – the audience One of the major audience considerations is howmuch background knowledge can be assumed andhow much must be explained The tone and style of your writing should vary with theaudience. Imagine writing about programming for:– Elementary school students– High school students– Your peers in college– A newspaper Consider your audience for COS 301 to be your peers You can assume that they know about things likevariables, objects, classes and types– They may not know about things like array slices, monads,exception handlers etc.– A PhD committee– A trade journal– An academic journalReadabilityReadability You should strive to produce prose that is readable andinformative You may have noticed that some academic journalsare rather difficult to read. Why?– The reader should not have to read a paragraph or sectiontwice to grasp its meaning– The reader should be able to follow your train of thought andunderstand the concepts that your are trying to convey In measuring readability, the two main metrics aresentence length and word complexity (number ofsyllables) Your goal in writing for this class is not to show offyour erudition or impress me with your knowledge –it is to produce clear, concise and easy-to-read prose If you are familiar with reading grade level, you canconsider grade 12 to be a target level– Words containing more than two syllables are considered“hard”– Long sentences are more difficult to read than short sentences1
Tone and StyleTone and Style One of the goals of this course is to develop someskills in written presentation of technical material You will be writing within a highly-structuredformal framework but your writing does not have tobe stiff, stilted and overly formal In each paper that you write, consider that there aretwo goals:In past classes I have noted that when students striveto be too formal, the writing style suffers greatly– However, the same students often write well when theyfeel less constrained – for example, in a take-home examessay that asks only for their opinion Your goal is to communicate with your peers.– You are not writing a textbook for beginning programmers– You are not writing to impress me with your esotericknowledge1. To convey to the reader an overview of the languageaspect or aspects covered in the paper2. To convey to the reader your personal assessment oflanguage featuresSo Avoid excessive informality Write naturally, but avoid excessive informality Do not write dense verbiage that conveys what shouldbe obvious to your peers"Are Java and Javascript programming paradigms similar?Sort of . maybe.""As you can see, there were a lot of scripting languagesfloating around (and more today)""On top of the numeric data types, Python also has nativecontainer types and strings" Feel free to express an opinion, but support it:– With arguments– With citations (opinions of others)– With examplesAvoid colloquial language, unless it is used to makea point Use the first person ("I ") judiciously, and use thethird person ("You ") even more judiciously– "You can call things such as the square root function byfirst importing sqrt from math .Don't state the obviousDo express opinions (and support them) Remember your audience – "When a program is running, regardless of what language itis written in, it is allocated a certain amount of memory toperform its tasks."– "You can use logical NOT to say something like, x ! 2,which will evaluate to true if x is equal to anything but 2,and false is x is equal to 2."– "Python's syntactic structure is similar to Java and othercurly brace languages, but different because of the lack ofcurly braces."Perl is a unique, interesting, and capable language that has been quitepopular since its introduction. The language is best suited for webprogramming, file and text manipulation, and common UNIX system tasks.It allows tasks that used to take multiple programming languages and hoursof time to be completed in mere minutes, which gives credence to itsnickname, “The Swiss Army chainsaw of programming languages”. It isone of the most flexible languages ever designed, which reinforces its otherslogan, “There’s more than one way to do it”. All of the flexibility, power,and expressiveness of the language can either be viewed as an advantage ordisadvantage for Perl. Very experienced Perl programmers will argue thatit is an advantage that no other languages have. Proponents of otherlanguages argue that the language is too big. The C language, for example,is very small. The C Programming Language (Kernigan, Ritchie), the defacto reference book on C that covers the entire language is only 294 pages.The de facto reference that covers the entirety of Perl, Programming Perl(Wall, Christiansen, Orwant) is 1092 pages.2
The Mayfield HandbookBasic Elements of Writing The Mayfield Handbook of Scientific and TechnicalWriting – An excellent resource and reference for all types oftechnical writing Abbreviated version is available online athttp://www.mhhe.com/mayfieldpub/tsw/toc.htmIf you have mastered these, you’re 90% there 1. Spelling2. Word Usage3. Grammar4. Sentence Structure5. Paragraph StructureSpellingWord Usage The most fundamental element of writing – regardlessof what else is wrong, spelling should be correct Dictionaries and thesauri are helpful in describinghow to use a word If you are not sure how to spell something, use tools: It’s a good idea to have a dictionary handy wheneveryou write, especially if you are unsure of spelling andusage– Spelling checker (don’t rely on it blindly!)– Dictionary– Thesaurus– Google English is rich in homonyms or near-homonyms thatare commonly misused. Ex: It also helps to know how to pronounce words– complement, compliment Try howjsay.com– affect, effecthttp://www.howjsay.com/index.php– accept, exceptWord Usage – Formal StyleGrammar Reports for this class are to be written in a formalstyle Grammar is the set of rules by which sentences areconstructed The guidelines below are not absolute. Skilled writersmay make exceptions See Mayfield handbook chs 11-14 for a basic review– Avoid first person constructions Poorly constructed sentences may still begrammatically correct– Avoid contractions– Avoid colloquial language The notation “informal” on your papers means that aword, phrase or sentence is too informal3
Sentence StructureSentence Structure Probably the most common type of problem in papers It’s worth the few minutes it takes to review thesetypes of errors Mayfield Ch. 6 classifies common errorsStacked Modifiers and NounsWordinessOverloaded SentencesSentence FragmentsComma SpliceFused SentencesStringy SentencesAgreementLack of ParallelismChoppy SentencesMisplaced ModifiersDangling ModifiersDouble NegativesFaulty ComparisonsInappropriate ShiftsSequence of tensesPronoun ReferencePronoun Case Sometimes we will note a specific type of sentenceerror when grading your papers, e.g., “fragment” or“comma splice.” Often a sentence will be noted simply with “rewrite”or “awk” (awkward).Paragraph StructureCoherence Paragraphs consist of several sentences in a group.Together the sentences discuss one subject, oftenintroduced in the first sentence (sometimes called thetopic sentence) Coherence definitions: The topic sentence is usually the first sentence in theparagraph and is often the most general sentence All other sentences should contribute to anunderstanding of the topic sentence Paragraphs should follow a logical organization witha beginning, middle and end– "the quality of being logical and consistent"– "capable of thinking and expressing yourself in a clear andconsistent manner"– "logical and orderly and consistent relation of parts" Coherence in writing– The writing flows clearly, logically and is consistentlyorganized Each paragraph contributes to the meaning of the paper Each sentence contributes to the meaning of the paragraph Each phrase contributes to the meaning of the sentenceCohesionParagraph Types "The big parts of a story should stick together, but thesmall parts need some stickum as well. When the bigparts fit, we call that good feeling coherence; whensentences connect, we call it cohesion." [1] Paragraphs follow typical patterns based on the modeor purpose of the paragraph:– (Roy Peter Clark, Writing Tools: 50 Essential Strategies forEvery Writer. Little, Brown, parison and contrastAnalogyCause and effectClassification and divisionDefinitionAnalysisEnumeration Let’s look online at some descriptions4
Types of Technical WritingReports There are many different types of technical writing,such as proposals, literature reviews, theses, technicalmanuals, end-user manuals, journal articles, etc. Reports can be further categorized:– Laboratory Reports– Research Reports See Mayfield Ch. 2– Research Articles Each type of technical writing follows a specificformat, with some variation– Design and Feasibility Reports We are primarily interested in Reports.– – Progress ReportsResearch ReportsThe Research Report Process From the Mayfield Handbook1. Define the problem“Research reports present the results of formalinvestigations into the properties, behavior, structures,andprinciples of material and conceptual entities.”2. Research the problem3. Present your research in a focused, coherentdocument Let’s talk about exactly what the “problem” is forCOS 301– Properties, behavior, structure etc of a language– Design principles embodied in the languageResearch and Survey ReportsSurvey Reports In this class your reports are a survey of existingknowledge rather than creation of new knowledge byresearch.A research report may have quite a few sections,following a defined sequence:3.4.1 Introduction* 3.4.1.1 Problem Statement* 3.4.1.2 Purpose* 3.4.1.3 Scope* 3.4.1.4 Authorization3.4.2 Background3.4.3 Theory3.4.4 Design and Decision Criteria3.4.5 Materials and Apparatus3.4.6 Procedure3.4.7 Work Plan3.4.8 Results3.4.9 Discussion3.4.10 Conclusion For each report you will be given a list of topics Your goals are to clearly and concisely presentmaterial about each topic (not easy!) for your chosenlanguage."I am sorry to have wearied you with so long a letter but I did nothave time to write you a short one" (attributed to Blaise Pascal)In this class the “research” is more like a survey ofexisting knowledge5
Report StructureSections and Subsections Research reports are divided into front matter, bodyand end matter Reports should be organized into sections andsubsections Front matter:– Title page– Abstract– Table of Contents– List of Figures Front matter is numbered with lowercase Romannumerals.– The title page is page i but is not usually explicitlynumbered. The abstract is page ii, etc.Sections and Subsections Organization into sections and subsections helps thereader understand the report and contributes toreadability It is often helpful to outline the report before startingto write – it helps you to organize your thoughts– Each section is distinct part of the report and has adescriptive heading– Subsections are distinct parts of the section and havedescriptive headings– A subsection may be as short as a single paragraph buttypically contains two or more The collection of sections and subsections is anoutline of the documentTitle PageThe titleshould saysomethingmeaningful Number your sections and subsections, e.g.1. Data Types1.1 Scalar Types1.2 Arrays and Structures1.2 Objects You may use one or more additional levels if desiredAbstractAbstract The abstract is a brief summary consisting of a singleparagraph, several sentences and typically less than150 words It provides a concise summary of the problem,method, results and conclusion of your report For this class method and results may not apply Always write an abstract6
Table of ContentsTable of Contents Most word processors can generate theseautomatically. Review your word processor’s helpfiles and learn how to do one. Do include front matter, except the TOC itself; bodyand end matter.List of FiguresList of Figures If you have figures (including tables) in your text theyare indexed separately in a List of Figures It may be convenient to copy tables, lists and otherillustrations from web references when coveringlanguage features such as operators or types– There is no reason not to do this as long as you cite yoursource!– These would typically appear in a list of figures– Note that large tables and figures copied from sources arenot considered in the written page count for assignmentsFiguresThe Report Body In addition to graphical illustrations, figures caninclude tables and even programming code examples. Starts with the title (yes again) at the top of the page Has an introduction Presents research or survey information Presents conclusions Usually your report body will reflect the topicsassigned in the project7
The Basic Rule of Reporting and PresentingSupport and Supporting Material1. Tell them what you’re going to tell them(introduction) When writing about a new language you will often beexpressing your opinion about the language2. Tell them3. Tell them what you’ve told them (summary andconclusions) Typically in an oral presentation brief conclusionsmay be presented at the beginning In a written research or survey report briefconclusions are presented in the abstract, but not thereport introduction– Opinions are fine things but only worthwhile if backed upwith facts, citations and/or arguments– In discussing a programming language, facts may be hard tocome by to support an opinion such as "this programminglanguage is not well suited to scientific computing." But you can support your opinions with citations or arguments Adequate support contributes to coherenceExamples of SupportIntroductions " All though Perl supports all of the above syntax for subroutines, themost common by far is sub NAME BLOCK. As will be shown in section2.3, all though compile-time argument checking (PROTO above) is allowedin a limited form, arguments are typically accessed through the specialvariable @ . The support for prototypes and attributes (ATTR above) islimited and is only used in very specific circumstances [21]. As such, itwill not be detailed in this report." Reports are typically divided into numbered sections" Perl attempts to meet every single need of its users, but I believe thatno language is capable of that, and that Perl falls very short of that goal. Itappears that over time features have been added to the language justbecause some other language has supported them. The object-orientedfeatures added in Perl 5 feel like a half-hearted attempt and their usage canbe quite dangerous since private instance variables do not exist. It isreminiscent of attempting object-oriented programming in C, which onlycontains structures." This is a lot like paragraph structure (topic sentence,supporting sentences, conclusion) on a larger scale Example The report itself, and each major section, begins withan introduction The introduction is not labeled as such The introduction provides motivation for a report orsection and identifies topics, problems, or issues– It does not present a conclusion. It is not an abstract!Surveying a topic for a language It is very easy to fall into “laundry list” mode whereyour simply provide a “laundry list” related to thetopic in question For example, when describing types available in alanguage, it is tempting to simply list the types with abrief description8
Remember your audienceIncluding Tables and Lists This is where it helps to remember your audience Short tables and lists (typically 1/3 of a page or less)may be included in the text– You can assume that your audience already knows aboutthe basic scalar types (characters, integers, floats, booleans)available in most languages Longer tables or lists should be included asappendices– Instead of a laundry list, you might present a table of types,and indicate that a language supports the usual scalar typesand then go on to describe more interesting points of thetype systemReports and ProgramsTypography Each assignment has an associated program that youwill write, usually related to the topics of the report Whether including program code in the body of thereport or in an appendix, use a monospaced font suchas Courier New or Lucida Console You can include a section that discusses how theprogram was written, how it operates, and how itdemonstrates features of the language Compare this codefunction showdiv(id) {//safe function to show an element with a specified idif (document.getElementById) { // DOM3 IE5, NS6document.getElementById(id).style.display 'block';} else {if (document.layers) { // Netscape 4document.id.display 'block';} else { // IE 4document.all.id.style.display 'block';}} The program itself will go into an appendix}TypographyEnd Matter With this code End matter typically includes references, appendicesand indexesfunction showdiv(id) {//safe function to show an element with a specified idif (document.getElementById) { // DOM3 IE5, NS6document.getElementById(id).style.display 'block';} else {if (document.layers) { // Netscape 4document.id.display 'block';} else { // IE 4document.all.id.style.display 'block';}} For this class you have references and appendices(your program and output)}9
ReferencesReferences In publications and proposals one of the cardinal rulesis that any reference listed in a reference section orbibliography must be cited in the text References are outside sources cited or quoted in yourpaper For this class we will ignore this rule. You willdevelop and maintain an annotated bibliographythroughout the semester– References cited in earlier papers need not be cited in laterpapers. For that matter you can consider that your main workproduct for the semester is one large report withseveral chaptersAnnotated Bibliography– They may include both print and digital resources,preferably BOTH When you cite a reference, you typically make ageneral statement about some conclusion or statementof opinion in the reference – in your own words! It is far better to quote directly than to plagiarize byincluding or paraphrasing the author’s words as ifthey were your own.Example In addition to including the formal citation in astandard format an annotated bibliography includes asentence or two explaining exactly why the article orbook is usefulThe IEEE Citation FormatElements of the IEEE Citation-Sequence System The IEEE format is one of many “Uses a single sequentially ordered note-number tocite all references to each source mentioned in thetext.” [2] Other popular formats are American PsychologicalAssociation (APA), Modern Language Association(MLA), etc.– Side note: whenever you use an acronym in a paper, spell itout on the first occurrence followed by the acronym inparentheses Arranged by order of citation in the text (notalphabetically)– Thereafter just use the acronym See Mayfield Ch 1010
General StructureGeneral Structure Citation numbers are enclosed in square brackets (ex:[1]) rather than superscripts1 Author names are in normal name order, usually withinitials rather than first names. With multiple authorsuse a comma between all but the last pair of names IEEE encourages substituting reference numbers forthe name of the author– ex: “[1], [9], and [11] have demonstrated.”– ex: “Use ‘in [1]” instead of “in Williams et al.”– Ex. C. Meadow, L. Latour and P. Dickens Dates are given as dd mmm. Yyyy (when all parts arepresent)– Ex 9 Sep. 2009Sep. 20092009 Separation of elements: Except for a period endingthe title element of a book, IEEE format uses commasrather than periods to separate elements. Abbreviations, when used, are followed by a period.General StructureExamples (from [3]) Titles: Books– All significant words in book and journal titles arecapitalized– Titles of journal articles and enclosed in quotes, orunderlined, but only the first word is capitalized Page numbers are always preceded with p. or pp.C. W. Lander, Power Electronics, 3rd. ed., London: McGraw-Hill, 1993. Sections / chapters of booksG. K. Knopf and A. S. Bassi, "Biological-based optical sensors andtransducers," in Opto-mechatronic Systems Handbook: Techniques andApplications, Hyungsuck Cho, Ed. Boca Raton, FL: CRC Press, 2003, pp.195-210.Examples (from [3])Examples (from [3]) Papers from Conferences Online Journal ArticleA. H. Cookson and B. O. Pedersen, "Thermal measurements in a 1200kVJ. Farrell. (2007, May). In Wikipedia we trust? Cosmos Online [Online].compressed gas insulated transmission line," in Seventh IEEE PowerAvailable: http://www.cosmosmagazine.com/node/1339Engineering Society Transmission and Distribution Conference and Online Conference PaperExposition, 1979, pp. 163-167.X. Yang. (2003, Aug.). NIRA: a new Internet routing architecture. Journal ArticlesK. P. Dabke and K. M. Thomas, "Expert system guidance for libraryusers," Library Hi Tech, vol. 10, (1-2), pp. 53-60, 1992.Presented at ACM SIGCOMM FDNA 2003 Workshop. [Online]. g.nira.pdf Website (note unknown author)(2007, Mar.). Dr Jean Armstrong: Brief Biography [Online]. a/aboutarmstrong.html11
IEEE Style GuidelinesIEEE Style Guidelines Place note numbers directly after reference, not at theend of the paragraph (where superscript note numbersare often placed). Use of note numbers sometimes seems a little strange.In this example the first occurrence of [3] could bereplaced with a name: In general, use the note number in place of author’sname.Alan Kay, the designer and inventor of the Smalltalkprogramming language [3], IEEE Style GuidelinesWhy All the Guidelines? When more than one work is cited, separate notenumbers with commas in one set of square brackets,e.g., [1,3,7] It’s the norm in academic publishing Citation formats are quite strict and are intended toprovide a standardized set of data to readers Never cite information that is not “recoverable” orviewable/obtainable by the reader Avoid content and additional bibliographic materialsuch as you normally see in footnotes and endnotes –use parenthetical inserts instead– Ignore this rule for COS 301 as you will be preparing anon-standard annotated bibliographyAppendices (sometimes Appendixes)Appendices “In one or more appendixes, include materials that arenot essential parts of your main text but that willprovide useful reference information to readersseeking more detail.”[2] Avoid placing items with varying topics in the sameappendix You can include: Give each appendix a title and start on a new page– Detailed Explanations– Additional Diagrams– Additional Tables– Long Lists Label appendices with letters, e.g., Appendix A,Appendix B etc.Appendix AList of Types in Ada Appendix BProgram Listing Refer to each appendix in the paper– Program Listings relevant to the paper. A paragraph of explanatory material may be added12
Works Cited[1] R.P. Clark, Writing Tools: 50 Essential Strategiesfor Every Writer. New York, NY: Little, Brown, 2006[2] L. C. Perelman, J. Paradis, and E. Barrett, TheMayfield Handbook of Technical & Scientific Writing.Mountain View, CA: Mayfield Publishing Company,1998[3] (2006, Apr.). Institute of Electrical and ElectronicsEngineers (IEEE) style examples. [Online]. iting/ieee.html13
Types of Technical Writing There are many different types of technical writing, such as proposals, literature reviews, theses, technical manuals, end-user manuals, journal articles, etc. See Mayfield Ch. 2 Each type of technical writing follows a specific format, with some va
