Gas station without pumps

2015 February 25

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?

4 Comments »

  1. I just ran into this course about technical writing by Norman Ramsey (who is a computer scientist). How does it compare to your past technical writing courses?

    Comment by plam — 2015 February 26 @ 09:37 | Reply

  2. I know nothing about a tech writing course by Norman Ramsey, and you did not provide a link, so I still know nothing. I’m afraid I’m not interested enough to do the Google search to find it. You can do the comparison yourself, as my course descriptions and detailed assignments are at https://users.soe.ucsc.edu/~karplus/185/

    Comment by gasstationwithoutpumps — 2015 February 26 @ 17:01 | Reply

  3. Whoops. I thought I’d provided the link, but obviously not. I’m only vaguely interested, since I’ve never taught a course on writing. He claims that workshopping is much more efficient than revising. http://www.cs.tufts.edu/~nr/pubs/eng-abstract.html

    Comment by Patrick Lam — 2015 February 26 @ 20:53 | Reply

    • I glanced over his 34-page booklet for teachers, and found it to be rather different in style and intent. He was teaching a group of grad students and seems to spend a lot more time talking about writing than my classes do. My classes were aimed at undergrads, and had them do a lot of writing with substantial individual feedback and some rewriting. A big part of the difference may be from cultural differences between grad and undergrad courses, but I suspect that both classes rely heavily on idiosyncratic teaching styles.

      Comment by gasstationwithoutpumps — 2015 February 26 @ 21:49 | Reply


RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Create a free website or blog at WordPress.com.

%d bloggers like this: