Difference between revisions of "Standard Writing Guidelines"

From Mw_writing
Jump to: navigation, search
 
(6 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
[[Category:Guidelines]]
 
[[Category:Guidelines]]
  
Some guidelines apply to virtually all English writing.  The following guidelines should generally be followed for all pieces of writing.
+
Some guidelines apply to virtually all English writing.  One of the most commonly cited is Strunk and White's <i>Elements of Style</i>, which is a very short book that covers English grammar and style. 
 +
 
 +
There are also references which focus primarily on technical writing.  Donald Knuth et al. wrote a book titled <i>[http://tex.loria.fr/typographie/mathwriting.pdf Mathematical Writing]</i>, in which the first several pages briefly cover important topics in technical writing.  If you are in need of suggestions, ask almost anyone with a Ph.D., as writing skills are required to successfully get a Ph.D.
 +
 
 +
The following guidelines should generally be followed for all pieces of writing.
 +
 
 +
=Be honest=
 +
 
 +
One of the most effective ways to get your contribution ignored is to be dishonest about the work you have done.  Dishonesty can end a career (as was effectively the case when [http://en.wikipedia.org/wiki/Stephen_Ambrose#Criticism Stephen Ambrose] allegedly fabricated interviews with president Dwight D. Eisenhower).  Less severe dishonesty can get you reprimanded, or just get your paper rejected.  In any case, it is best to be honest.
 +
 
 +
==Cite your sources==
 +
 
 +
In whatever work you do, you will be standing on the shoulders of giants.  Acknowledge where you have gotten inspiration and words from, and give credit where credit is due.
 +
 
 +
==Admit shortcomings==
 +
 
 +
If you are presenting a system that has a weakness, don't be afraid to acknowledge it.  People reading or listening to you will be far more skeptical if they find a problem than if you admit it yourself.  There's no shame in having future work.<ref name="pitfalls">[http://www.cs.ubc.ca/labs/imager/tr/2008/pitfalls/ Tamara Munzner: Process and Pitfalls in Writing Information Visualization Research Papers]</ref>
  
 
=Use proper English=
 
=Use proper English=
Line 23: Line 39:
 
Having correct grammar is vital for communicating effectively.  Incorrect grammar can sometimes make it very difficult to understand what you are trying to say.  A full discussion of English grammar is beyond the scope of this wiki, but there are many books which address this topic.
 
Having correct grammar is vital for communicating effectively.  Incorrect grammar can sometimes make it very difficult to understand what you are trying to say.  A full discussion of English grammar is beyond the scope of this wiki, but there are many books which address this topic.
  
==Watch for homonym problems==
+
==Be careful with computer terms==
  
Several invalid phrases come from spoken English, where homonyms all sound the sameThere are many examples of this, but the most common ones are addressed here.
+
Some computer terms have special formatting considerations.  For instance, some programs, such as <tt>grep</tt> are canonically spelled in lowercase.  Most programming languages are also case-sensitive.  You may find it easier to reformat a sentence to avoid placing a case-sensitive word at the beginningAlso, it may occasionally make sense to break the common "punctuation inside quotation marks" rule in a context such as <b>The input string used was <tt>"Hello world"</tt>.</b>
 +
 
 +
==Watch for common problems==
 +
 
 +
Many expressions used in casual conversational English are invalid or improper in a formal setting.
  
 
===there/their/they're===
 
===there/their/they're===
  
All of these words have different meanings.  Their correct uses are generally as follows:
+
All of these words have different meanings.  Their correct uses are as follows:
 
* <b>there</b> refers to a location.
 
* <b>there</b> refers to a location.
 
* <b>their</b> means "belonging to them"
 
* <b>their</b> means "belonging to them"
Line 45: Line 65:
  
 
An object can be larger <b>than</b> another object, and if this is the case, <b>then</b> something else is true.
 
An object can be larger <b>than</b> another object, and if this is the case, <b>then</b> something else is true.
 +
 +
===infer/imply===
 +
 +
Infer and imply have complementary meanings. To <b>infer</b> means to logically deduce from indirect evidence, while to <b>imply</b> means to suggest something indirectly.  Mixing these up will quite possibly cause people to misunderstand you.
 +
 +
===e.g. and i.e.===
 +
 +
These abbreviations come from Latin.  <b>I.e.</b> stands for <i>id est</i> which means "That is."  <b>E.g.</b> stands for <i>exempli gratia</i> which means "For example."  Be careful not to mix these up.<ref name="wikihow-ie">[http://www.wikihow.com/Use-%22i.e.%22-Versus-%22e.g.%22 wikiHow: How to use "i.e." Versus "e.g."]</ref>
  
 
===And more===
 
===And more===
  
 
Many other words are commonly misused.  Looking at the [http://en.wikipedia.org/wiki/List_of_commonly_misused_English_words list on wikipedia] should help you avoid these mistakes.
 
Many other words are commonly misused.  Looking at the [http://en.wikipedia.org/wiki/List_of_commonly_misused_English_words list on wikipedia] should help you avoid these mistakes.
 +
 +
=Use proper math notation=
 +
 +
If you plan on using mathematical notation in your writing, you should pay attention to additional formatting advice.  [http://www.math.ohio-state.edu/~goss/hint.pdf David Goss' <i>Some Hints on Mathematical Style</i>] has a good collection of advice related to writing with math.  Some of the points (e.g. define terms before using them) are analogous to general writing advice, while others (e.g. make the distinction between the existential and universal qualifier clear) are more specific.
  
 
=Edit well=
 
=Edit well=
Line 58: Line 90:
 
Depending on where you are sharing your work, the appropriate writing style can vary greatly.  With this is mind, it is a good idea to carefully read the other works presented at the venue, and ensure your tone is appropriate.  The following advice, however, generally holds true.
 
Depending on where you are sharing your work, the appropriate writing style can vary greatly.  With this is mind, it is a good idea to carefully read the other works presented at the venue, and ensure your tone is appropriate.  The following advice, however, generally holds true.
  
==Avoid business lingo==
+
==Use clear language==
 +
 
 +
Writing is meant to be understood, so it is a good idea to make writing as clear as possible.  Don't try to make writing fancier by using obscure synonyms of common words.  Some journal authors<ref name="psych-published">[http://pb.rcpsych.org/cgi/reprint/2/6/112 The Psychiatrist: How to Get Your Paper Published]</ref> say that a paper is not a good paper unless it is as clear as it can be.  Similarly, if you must use field-specific terminology (especially if that terminology is not quite standard) <i>define it.</i>  It's better to spend a paragraph ensuring everyone understands your message rather than having half the readers misunderstand you.
  
Try to avoid language that sounds like it was written by a marketer or bureaucrat. This sort of language is not typically used in academia, and its use may make others think that you are trying to hide something.
+
Also, avoid needlessly fancy words.<ref name="strunkandwhite">Strunk and White. <i>The Elements of Style, fourth edition</i></ref> More complicated words might make your writing feel more sophisticated, but it is in opposition to the primary goal of writing: to communicate ideas.  Additionally, using words that have a business or marketing flavor might make some readers question whether you are trying to make your work sound better than it is, and could make them less receptive to your ideas.
  
==Use clear language==
+
===Avoid words like 'large' and 'fast'===
  
Writing is meant to be understood, so it is a good idea to make writing as clear as possible.  Don't try to make writing fancier by using obscure synonyms of common words.
+
You should want your writing to be as relevant to the future as possible.  Do not refer to datasets as 'large' as the meaning of  'large' will change with time.  As an example, a one gigabyte dataset now easily fits in almost any desktop computer's RAM, while less than twenty years ago, it would take a good deal of money to get a hard drive that could hold all that data.<ref name="pitfalls">[http://www.cs.ubc.ca/labs/imager/tr/2008/pitfalls/pitfalls.pdf Tamara Munzner: Process and Pitfalls in Writing Information Visualization Research Papers]</ref>
  
==Avoid needless synonyms==
+
==Be self-consistent==
  
Use the same term for the same thing in whatever you're writing.  Do not refer to something as a "technique" in one sentence and an "approach" in the nextDoing so can cause confusion, or at the very least make it less clear what you are referring to.
+
What you are writing is a single work, and so it should agree with itself.  Use the same term for the same thing throughout your writing.  If your introduction lists three topics you will be discussing, discuss them in the same order in the body of your paperBy being consistent, you are making it easier for the reader to understand and navigate what you've written, which makes it easier for your writing to fulfill its goals.
  
 
==Use active voice (when possible)==
 
==Use active voice (when possible)==

Latest revision as of 12:54, August 29, 2010


Some guidelines apply to virtually all English writing. One of the most commonly cited is Strunk and White's Elements of Style, which is a very short book that covers English grammar and style.

There are also references which focus primarily on technical writing. Donald Knuth et al. wrote a book titled Mathematical Writing, in which the first several pages briefly cover important topics in technical writing. If you are in need of suggestions, ask almost anyone with a Ph.D., as writing skills are required to successfully get a Ph.D.

The following guidelines should generally be followed for all pieces of writing.

Be honest[edit]

One of the most effective ways to get your contribution ignored is to be dishonest about the work you have done. Dishonesty can end a career (as was effectively the case when Stephen Ambrose allegedly fabricated interviews with president Dwight D. Eisenhower). Less severe dishonesty can get you reprimanded, or just get your paper rejected. In any case, it is best to be honest.

Cite your sources[edit]

In whatever work you do, you will be standing on the shoulders of giants. Acknowledge where you have gotten inspiration and words from, and give credit where credit is due.

Admit shortcomings[edit]

If you are presenting a system that has a weakness, don't be afraid to acknowledge it. People reading or listening to you will be far more skeptical if they find a problem than if you admit it yourself. There's no shame in having future work.[1]

Use proper English[edit]

Readers will judge your writing both on its meaning and on its mechanics. If you have great meaning but poor spelling or grammar, your work will be less well received.

Proper English means several things.

Have correct spelling[edit]

Spelling mistakes are some of the easiest mistakes to avoid in writing. Most programs support automatic spell-checking, and there are other tools for spell-checking text files.

Additionally, avoid misspellings that computers can't detect. For instance, the following sentence is correctly spelled.

Ho ware you doing?

Even though all the words in that sentence are spelled correctly, it is not correct. Look for errors such as these.

Have correct grammar[edit]

Having correct grammar is vital for communicating effectively. Incorrect grammar can sometimes make it very difficult to understand what you are trying to say. A full discussion of English grammar is beyond the scope of this wiki, but there are many books which address this topic.

Be careful with computer terms[edit]

Some computer terms have special formatting considerations. For instance, some programs, such as grep are canonically spelled in lowercase. Most programming languages are also case-sensitive. You may find it easier to reformat a sentence to avoid placing a case-sensitive word at the beginning. Also, it may occasionally make sense to break the common "punctuation inside quotation marks" rule in a context such as The input string used was "Hello world".

Watch for common problems[edit]

Many expressions used in casual conversational English are invalid or improper in a formal setting.

there/their/they're[edit]

All of these words have different meanings. Their correct uses are as follows:

  • there refers to a location.
  • their means "belonging to them"
  • they're stands for "they are"

You can find a more thorough discussion at [2]

its/it's[edit]

These two forms of its have quite different meanings. The correct usage is

  • its means "belonging to it"
  • it's means "it is"

than/then[edit]

An object can be larger than another object, and if this is the case, then something else is true.

infer/imply[edit]

Infer and imply have complementary meanings. To infer means to logically deduce from indirect evidence, while to imply means to suggest something indirectly. Mixing these up will quite possibly cause people to misunderstand you.

e.g. and i.e.[edit]

These abbreviations come from Latin. I.e. stands for id est which means "That is." E.g. stands for exempli gratia which means "For example." Be careful not to mix these up.[3]

And more[edit]

Many other words are commonly misused. Looking at the list on wikipedia should help you avoid these mistakes.

Use proper math notation[edit]

If you plan on using mathematical notation in your writing, you should pay attention to additional formatting advice. David Goss' Some Hints on Mathematical Style has a good collection of advice related to writing with math. Some of the points (e.g. define terms before using them) are analogous to general writing advice, while others (e.g. make the distinction between the existential and universal qualifier clear) are more specific.

Edit well[edit]

You should always edit your writing until you are satisfied with it and are unable to think of ways to improve it. You should have colleagues and friends read what you have written and look for mistakes. Frequently, a new set of eyes is able to find mistakes the original writer is blind to.

Use appropriate style[edit]

Depending on where you are sharing your work, the appropriate writing style can vary greatly. With this is mind, it is a good idea to carefully read the other works presented at the venue, and ensure your tone is appropriate. The following advice, however, generally holds true.

Use clear language[edit]

Writing is meant to be understood, so it is a good idea to make writing as clear as possible. Don't try to make writing fancier by using obscure synonyms of common words. Some journal authors[4] say that a paper is not a good paper unless it is as clear as it can be. Similarly, if you must use field-specific terminology (especially if that terminology is not quite standard) define it. It's better to spend a paragraph ensuring everyone understands your message rather than having half the readers misunderstand you.

Also, avoid needlessly fancy words.[5] More complicated words might make your writing feel more sophisticated, but it is in opposition to the primary goal of writing: to communicate ideas. Additionally, using words that have a business or marketing flavor might make some readers question whether you are trying to make your work sound better than it is, and could make them less receptive to your ideas.

Avoid words like 'large' and 'fast'[edit]

You should want your writing to be as relevant to the future as possible. Do not refer to datasets as 'large' as the meaning of 'large' will change with time. As an example, a one gigabyte dataset now easily fits in almost any desktop computer's RAM, while less than twenty years ago, it would take a good deal of money to get a hard drive that could hold all that data.[1]

Be self-consistent[edit]

What you are writing is a single work, and so it should agree with itself. Use the same term for the same thing throughout your writing. If your introduction lists three topics you will be discussing, discuss them in the same order in the body of your paper. By being consistent, you are making it easier for the reader to understand and navigate what you've written, which makes it easier for your writing to fulfill its goals.

Use active voice (when possible)[edit]

The active voice (as opposed to the passive voice) should be used whenever possible. Using active phrasing makes sentences stronger, clearer, and shorter. Sentences can be easier to understand when in the active voice.

However, some authors prefer, in academic writing, to avoid using first- or second-person pronouns. In this case, passive construction is essential. Before writing, you should decide which choice to make.

References[edit]

<references>
  1. 1.0 1.1 Tamara Munzner: Process and Pitfalls in Writing Information Visualization Research Papers Cite error: Invalid <ref> tag; name "pitfalls" defined multiple times with different content
  2. How to Use There, Their and They're
  3. wikiHow: How to use "i.e." Versus "e.g."
  4. The Psychiatrist: How to Get Your Paper Published
  5. Strunk and White. The Elements of Style, fourth edition