Freshman design seminar writing notes

Along with the senior-thesis writing course this quarter, I’m also teaching a freshman design seminar. Many of the problems in their first design reports are similar to the problems I see in senior theses (Senior thesis pet peeves, More senior thesis pet peeves, and Still more senior thesis pet peeves). I hope that by catching them early, I can squelch the problems.

Here are some things I saw in the first design report turned in by the freshmen:

• Every design document should have a title, author, and date. If the document is more than one page log, it should have page numbers.
• Passive voice should be used very sparingly—use it to turn sentences around to pull the object into the first position, when that is needed to get a smooth old-info-to-new-info flow.  Sometimes you can use it to hide the actor, when you really don’t know who did something, but that should be very rare.
• Errors in schematics, programs, block diagrams, and other low-redundancy representations are very serious.  In the circuits class, any error in a schematic triggers an automatic REDO for the assignment.  I’m not as harsh in the freshman design class, but there is no notion of “just a little mistake” in a schematic.
• The battery symbol is not the right way to show a voltage source that is not a battery.  Use the power-port symbol, to indicate connect to a power supply that is not included in the schematic, or include the Arduino board from which you are getting power as a component in the schematic.
• Bar charts are not appropriate for all that many data representations in the physical and biological sciences.   If you have 2-D data, use a scatter diagram.  A bar should only be used when the area of the bar communicates the quantity of something that is labeled in discrete classes.  (And even then a single point is often clearer.)
• Captions on figures should be about a paragraph long.  Remember that people generally flip through a paper looking at the pictures before deciding whether to read it.  If the figures and captions are mysterious, they’ll give up without ever reading the paper.  A lot of academic authors, when writing a paper for publication, start by choosing the figures and writing the captions.  Those figures and captions then form the backbone of the paper, which is written to explain and amplify that backbone.
• In academic writing, figures are treated as floating insertions, not fixed with respect to the text.  Therefore, it is correct to refer to the figures by name, “Figure 1”, but not by location (“above” or “below”). Every figure in a paper should be referred to explicitly by name in the main body of the text, and the floating insertion put near where the first reference to the figure occurs.
• Citations in modern scholarly works are not done as footnotes—those went out of style 50 or 60 years ago, and only high school teachers still use that style.  Modern papers put all the citations at the end (in any of several different styles, usually specific to a particular journal).  I have a slight preference for reference lists that are sorted by author, rather than by order cited in the paper, and I have a preference towards high-redundancy reference list formats rather than minimalist ones, but I don’t have a particular style that I recommend.
• There is no point to saying “web” in a citation—if something comes from the web, then give me the URL (or DOI). For material that is only on the web (not citable as a journal article), you must give the URL or DOI.
• When typing numbers, never start them with a decimal point—use a leading zero to prevent the easily missed leading decimal point. Even better is to follow the engineering convention of using numbers between 1 and 1000 with exponents of 10 that are multiples of three.  That is, instead of saying .01, or even 0.01, say 10E-3.  The advantage is that the powers of 1000 have prefix names, so that .01A becomes 10mA.  Don’t worry about significant figure meanings, because engineers express significance explicitly, not through imprecise sig-fig conventions.  That is, and engineer would say 10mA±2mA, not 1.E-2A (which a physicist would interpret as 10mA±5mA) or 1.0E-2A (which a physicist would interpret as 10mA±0.5mA).
• In describing where components are in a schematic diagram, “before” and “after” don’t make much sense.  I have no idea what you mean if you say that a resistor is before an LED. When engineers use “before” or “after” it is generally in an information-flow sense.  For example, you may filter before amplifying or amplify before filtering, but if a resistor and capacitor are in series, neither is “before” the other.
• Students use “would” in many different ways, but mostly incorrectly, as if it were some formal form of “was” or “will be”, while it is actually a past subjunctive form of the modal auxiliary “will”.  There are many correct uses of “would” in general English, but in technical writing, it is usually reserved for “contrary to fact” statements. When a student writes “I would grow bacteria for 2 days”, I immediately want to know why they don’t.
• The pronoun “this” is very confusing, as the reader has to work out what antecedent is meant. A lot of effort can be saved if “this” and “these” are not used as pronouns but only as demonstrative adjectives modifying a noun. This usage is much easier for people to follow, as the noun helps enormously in figuring out the antecedent.  If you can’t figure out what noun to use, then your reader has no hope of understanding what you meant by “this”.
• “First” is already an adverb and needs no -ly. The same is true of “second”, “third”, and “last”.  For some reason, no one makes the mistake with “next”, which follows the same pattern of being both an adjective and an adverb.  I wonder why that is?

Long sentence

Joseph Mitchell created a marvelous long sentence (found in A City of Many Pasts in The New Yorker):

And I should also say that when I say the past I mean a number of pasts, a hodgepodge of pasts, a spider’s web of pasts, a jungle of pasts: my own past; my father’s past; my mother’s past; the pasts of my brothers and sisters; the past of a small farming town geographically misnamed Fairmont down in the cypress swamps and black gum bottoms and wild magnolia bays of southeastern North Carolina, a town in which I grew up and from which I fled as soon as I could but which I go back to as often as I can and have for years and for which even at this late date I am now and then all of a sudden and for no conscious reason at all heart-wrenchingly homesick; the pasts of several furnished-room houses and side-street hotels in New York City in which I lived during the early years of the Depression, when I was first discovering the city, and that disappeared one by one without a trace a long time ago but that evidently made a deep impression on me, for every once in a while the parlor or the lobby of one of them or my old room in one of them turns up eerily recognizable in a dream; the pasts of a number of speakeasies, diners, greasy spoons, and drugstore lunch counters scattered all over the city that I knew very well in the same period and that also have disappeared and that also turn up in dreams; the pasts of a score or so of strange men and women—bohemians, visionaries, obsessives, impostors, fanatics, lost souls, gypsy kings and gypsy queens, and out-and-out freak-show freaks—whom I got to know and kept in touch with for years while working as a newspaper reporter and whom I thought of back then as being uniquely strange, only-one-of-a-kind-in-the-whole-world strange, but whom, since almost everybody has come to seem strange to me, including myself, I now think of, without taking a thing away from them, as being strange all right, no doubt about that, but also as being stereotypes—as being stereotypically strange, so to speak, or perhaps prototypically strange would be more exact or archetypically strange or even ur-strange or maybe old-fashioned pre-Freudian-insight strange would be about right, three good examples of whom are (1) a bearded lady who was billed as Lady Olga and who spent summers out on the road in circus sideshows and winters in a basement sideshow on Forty-second Street called Hubert’s Museum, and who used to be introduced to audiences by sideshow professors as having been born in a castle in Potsdam, Germany, and being the half sister of a French duke but who I learned to my astonishment when I first talked with her actually came from a farm in a county in North Carolina six counties west of the county I come from and who loved this farm and started longing to go back to it almost from the moment she left it at the age of twenty-one to work in a circus but who made her relatives uncomfortable when she went back for a visit (“ ‘How long are you going to stay’ was always the first question they asked me,” she once said) and who finally quit going back and from then on thought of herself as an exile and spoke of herself as an exile (“Some people are exiled by the government,” she would say, “and some are exiled by the po-lice or the F.B.I. or the head of some old labor union or the Mafia or the Black Hand or the K.K.K., but I was exiled by my own flesh and blood”), and who became a legend in the sideshow world because of her imaginatively sarcastic and sometimes imaginatively obscene and sometimes imaginatively brutal remarks about people in sideshow audiences delivered deadpan and sotto voce to her fellow-freaks grouped around her on the platform, and (2) a street preacher named James Jefferson Davis Hall, who also came up here from the South and who lived in what he called sackcloth-and-ashes poverty in a tenement off Ninth Avenue in the Forties and who believed that God had given him the ability to read between the lines in the Bible and who also believed that while doing so he had discovered that the end of the world was soon to take place and who also believed that he had been guided by God to make this discovery and who furthermore believed that God had chosen him to go forth and let the people of the world know what he had discovered or else supposing he kept this dreadful knowledge to himself God would turn his back on him and in time to come he would be judged as having committed the unforgivable sin and would burn in Hell forever and who consequently trudged up and down the principal streets and avenues of the city for a generation desperately crying out his message until he wore himself out and who is dead and gone now and long dead and gone but whose message remembered in the middle of the night (“It’s coming! Oh, it’s coming!” he would cry out. “The end of the world is coming! Oh, yes! Any day now! Any night now! Any hour now! Any minute now! Any second now!”) doesn’t seem as improbable as it used to, and (3) an old Serbian gypsy woman named Mary Miller—she called herself Madame Miller—whom I got to know with the help of an old-enemy-become-old-friend of hers, a retired detective in the Pickpocket and Confidence Squad, and whom I visited a number of times over a period of ten years in a succession of her ofisas, or fortune-telling parlors, and who was fascinating to me because she was always smiling and gentle and serene, an unusually sweet-natured old woman, a good mother, a good grandmother, a good great-grandmother, but who nevertheless had a reputation among detectives in con-game squads in police departments in big cities all over the country for the uncanny perceptiveness with which she could pick out women of a narrowly specific kind—middle-aged, depressed, unstable, and suggestible, and with access to a bank account, almost always a good-sized savings bank account—from the general run of those who came to her to have their fortunes told and for the mercilessness with which she could gradually get hold of their money by performing a cruel old gypsy swindle on them, the hokkano baro, or the big trick; and, finally, not to mention a good many other pasts, the past of New York City insofar as it is connected directly or indirectly with my own past, and particularly the past of the part of New York City that is known as lower Manhattan, the part that runs from the Battery to the Brooklyn Bridge and that encompasses the Fulton Fish Market and its environs, and which is part of the city that I look upon, if you will forgive me for sounding so high-flown, as my spiritual home.

Although this sort of long sentence may be amusing as a tour de force in literary writing, marvelous mainly for its ability to remain grammatical, despite the length, I hope never to see such a long sentence in technical writing.

Still more senior thesis pet peeves

I previously posted some Senior thesis pet peeves and More senior thesis pet peeves. Here is another list, triggered by a couple of groups of second drafts (in no particular order, though some are repeats of earlier ones—the students hadn’t gotten the message):

• Passive voice is not to be used. When passive voice is used, the reader has a hard time figuring out who actually did anything. A thesis is written toestablish that someone is competent to do research and write about it. If the entire thesis is written in passive voice, with no first-person singular, the implication is that all the work was done by person or persons unknown.If you did the work, claim it! If you didn’t do the work, tell me who did!
• “however”≠”but”: “However” is a sentence adjective, but it is not a conjunction. “However” is best used in the middle of a sentence—it can, however, be moved to the beginning, if necessary for readability. However, there is some danger when it is at the beginning of a sentence of merging the sentence with the previous one, and treating it like a conjunction. If you make that mistake, replace “however” and the following comma with “but”.
• A number of students are using dangling modifiers: starting sentences with modifiers that would apply to the subject of the sentence, then changing their mind and putting a different subject in the main part of the sentence.  (I won’t embarrass students by quoting their work here—there are a number of examples at http://examples.yourdictionary.com/examples-of-dangling-modifiers.html.)
• Lists need to consist of parallel items.  The items need to be grammatically parallel as well as semantically parallel. If one is a noun phrase, then all need to be noun phrases.  If one is a verb clause, they all need to be verb clauses.  The semantic parallelism is a little subtler—don’t mix properties of an object with instructions for using the object, for example.  The bulleted lists of visual aids for talks are a particularly important place to apply the rules of parallelism.
• I recommended that students start each chapter on a new page. Not only is this conventional book and thesis formatting, but starting each chapter on a new page makes it easier for the reader to distinguish between chapter breaks, section breaks, and subsection breaks.  Anything that makes it easier for a reader to stay oriented in a large document is useful. (I also recommended numbering sections and subsections with the chapter.section.subsection style used in most computer-science documents.
• Figures and tables should be sequentially numbered, and the name of the figure is the word “Figure” followed by an unbreakable space, followed by the number. Because this is the name of the figure, it is capitalized like other proper nouns: Figure 1, Table 3, … . All figures should be referred to in the text, and the figures should appear near where the first reference to them is (unless there are a group of figures relegated to an appendix, with their existence mentioned in the main body, but not discussed there). If you need to insert a new figure, you need to renumber everything after that point—so make all your figure numbering be handled by automatic cross references by the program, as manual renumbering is highly error-prone. If you have a name like Figure 2b, it means a subfigure of Figure 2, not a figure you added late between the old Figures 2 and 3.  (Incidentally, I hate how WordPress throws away unbreakable spaces when converting back and forth between “Visual” and “Text” editing.  No matter how carefully I put them in, WordPress manages to mess them up and turn them back into ordinary spaces.)
• “parse”≠”scan”: Every year I get a number of students who have picked up the word “parse” from a computer science class, and misunderstood it to be a synonym for “scan”. That’s not what it means. To parse something is to determine its structure—to break it into parts and analyze the relationship among the parts (generally in terms of some grammar). The verb “parse” is transitive—it takes an object, not a prepositional phrase, that holds the thing being analyzed.
• Students are still having trouble with countable and uncountable nouns. For some students, this is understandable, as their native languages do not make the countable/uncountable distinction that English does.  I pointed students to the Oxford Student Dictionary of American English, edited by Hornby, which is now out of print, as being a dictionary that actually tells you whether a noun is countable or not.  The Oxford Advanced American Dictionary for learners of English is not as nicely formatted, but also has the [C] and [U] markings and is still in print.I used two examples of nouns that changed meaning depending on whether they were countable:  “grub” and “time”.  “Grub” is food, but “a grub” is the larval form of an insect, which may or may not be food. “Time”, when uncountable, is a duration, but “times”, when countable, are separate events.

  Even native speakers of English sometimes mess up the countable/uncountable distinction (though usually not with articles). The contexts where native speakers mess up are “amount of”/”number of”, “less”/”fewer”, and “much”/”many”—in all of which the first form should be used with uncountable nouns and the second with plural forms of countable nouns.