General Rules of Technical Writing

This is a post summarizes the things I learned over the course of revising my master’s thesis, including writing, latex tips. A lot of thanks to Prof. Alan Cox and  Prof. John Mellor-Crummey for their  feedback on my thesis draft.

  1. Organization of Contents
    1. In the thesis, there should be a short introduction paragraph as an overview of the chapter
    2. Write a summary paragraph at the end of the results section, to summarize the key results and take aways.
  2. Text Content
    1. Number less than 10 should be written in work, for example “one”
    2. Use more active tense rather than passive tenses
    3. If we use an acronym, make sure it is defined previously
    4. Be consistent with the terms, or it can come back and hunt you in later revisions
    5. Don’t use “incur” unless “incurs”
    6. Avoid redundant phrases
      1. in order to –> to
    7. Compare
      1. Use “better than” when comparing two configurations, use “than” more, less “compared to”
        1. The eight ChildJVMs with one map slot per ChildJVM configuration uses close to two times heap memory more heap memory than the four ChildJVMs with one map slot per ChildJVM
      2. Use “as compared to” when comparing two configurations instead of “comparing to”
    8. Use “this” more than “the”
      1. “This paper” refers to the paper that was discussed immediately before
    9. Describing range
      1. between… and ..
      2. from .. to…
    10. Describe linear relations
      1. Linear in “the size of ….”
    11. Describe change in amount
      1. Reduction “in” something, e.g. reduction in memory usage
    12. In sentence Cluses
      1. …, including …., (use a comma after the including part)
    13. Listing items
      1. Use “such as”, when listing a single item
      2. Use “including”, when listing a subset
      3. Use”:”, when listing every element
    14. Use “This thesis” rather than “my work”
  3. Figures, Tables, Code segments
    1. All references to “Table, Figure” should be capitalized
    2. Figures on the top of the page
    3. Figures and Tables should come after the first mentioning
    4. Code segments
      1. Single space for tables and code segments  to make them more compact
      2. Put a verbatim section in a figure to add caption, labels and reference it easier
        1. Example can be found here, http://tex.stackexchange.com/questions/98170/center-verbatim-text-in-figure
    5. Don’t miss the full stop at the end of a citation
    6. Make sure every Figure, Table, Code segment is well explained
    7. Figure
      1. label has to come after caption to reference the figure.
    8. Referencing a Figure
      1. Don’t need to use “The Figure” or “This Figure” to reference a figure
  4. Bibliography
    1. Use {M}apreduce to make sure “Mapreduce” is shown with the M capitalized
    2. Even for tech report, it is required to say “journal = school, tech report”
Advertisements
This entry was posted in Writing. Bookmark the permalink.

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