Difference between revisions of "Standard Writing Guidelines"
|Line 1:||Line 1:|
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.
The following guidelines should generally be followed for all pieces of writing.
Latest revision as of 13: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.
- 1 Be honest
- 2 Use proper English
- 3 Use proper math notation
- 4 Edit well
- 5 Use appropriate style
- 6 References
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
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.
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.
Use proper English
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
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
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
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
Many expressions used in casual conversational English are invalid or improper in a formal setting.
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 
These two forms of its have quite different meanings. The correct usage is
- its means "belonging to it"
- it's means "it is"
An object can be larger than another object, and if this is the case, then something else is true.
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.
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.
Many other words are commonly misused. Looking at the 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. 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.
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
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
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 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. 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'
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.
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)
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.
- Tamara Munzner: Process and Pitfalls in Writing Information Visualization Research Papers Cite error: Invalid
<ref>tag; name "pitfalls" defined multiple times with different content
- How to Use There, Their and They're
- wikiHow: How to use "i.e." Versus "e.g."
- The Psychiatrist: How to Get Your Paper Published
- Strunk and White. The Elements of Style, fourth edition