Technical Writing & Communication
Since many students taking the course did not appear to have had much background in technical writing and/or communication, I have attempted to provide some general tips and links here.
- Avoid informal style. Almost all term papers contained in-jokes or a chatty style, remember that your term paper is supposed to be a technical one. If your term paper reads like you are talking to a very good friend after a very long night in the pub, then you are doing something wrong. Keep your style technical. This is the number one fault with almost all term papers! Remeber that in English there is a bigger difference between the spoken and written language than in Swedish. This especially applies to technical articles.
- Never use the first person singular e.g., "I did this" or "I thought that". Use first person plural e.g., "We present this" or "We have built that". Note that this applies even if you are the only author!
- It is also acceptable to use the third person: "The authors claim that..."
- Always write your own text. If you cut'n'paste verbatim text from another source then this could land you in serious trouble!
- Do not talk to the audience e.g., "We think that this is stupid, but we know that you actually want to read about what we have done for the past ten weeks"
- Generally try to avoid being funny, unless you have a very good joke which is on-topic. What may seem funny when you write the term paper at 3am may not be quite so funny in the cold light of day.
- Do not use slang or colloquialisms.
- Consider your target audience. If your target audience is well-versed in computer networking, you can safely omit background material which describes the Internet and what it does.
- Avoid inappropriate content. References to porn, sex, ex-boyfriends or ex-girlfriends, and downloading films are not usually relevant to a technical term paper.
- Make sure that your references make sense i.e., your references and your use of references should be relevant to the content of your term paper.
- A good structure is critical for a well-written term paper. Write the structure and sanity-check it first before writing any content.
- Define terms, acronyms, jargon etc. as they are introduced. For example, "DNS (Domain Name System)".
- Be consistent in your terminology and your usage of terminology i.e., do not use four different names for the same thing.
- Clearly state when you are presenting your own opinions.
- Use a spellchecker.
- Get somebody else to proof-read your term paper before you submit it.
- Use LaTeX. It is the de facto standard document preparation system for scientific and mathematical articles. If you take the time to learn it now, it will be of great assistance in the future for writing exjobb reports etc.
- Read Writing Technical Articles.
- Read Common Bugs in Writing.
- Read Write that Essay!.
- Read. If you want to learn how to write well, you need to read a lot of high-quality content. Not only scientific articles, but good newspapers and good books will help you master how to communicate effectively.
- Read The Elements of Style.
- Read Guide to Punctuation.
- Read General Advice on Writing Computer Science articles.
- Read Books of General Interest to Computer Scientists. Try to peer through the typos!
Common English Mistakes
Singular vs. plural * Check verbs: - He rides his bike to work - They ride their bike to work Notice the "s" in "rides" in singular form. - Check "is" vs. "are", "has" vs. "have", "do" vs. "does": e.g., "cars are" vs. "a car is", "the car does", "the cars do" and: e.g., "the cat is black" vs. "the cat and the dog are black". * When to use "that" and "which". - Usually you use which after a comma, otherwise use "that". e.g.: The car drives down the street, which holds many secrets. The car drives down the street that holds many secrets. * Do not use contractions in formal writing: e.g., avoid it's, hasn't, won't, etc. instead use "it is", "has not", "will not", etc. * Never start sentences with "And". * Do not use "story telling", be concise: E.g., avoid: "therefore, we thought that we wanted to show how..." Instead write: "therefore, we show how..." * Plural vs. possession: Differentiate between: - The cars seats are comfortable <--- WRONG (plural) - The car's seats <--- RIGHT (possession). - Common exception: it's = "it is" its (possession) * Names are capitalized: e.g., "the Internet", when refering to the specific Internet.
- Practice your talk beforehand. A well-rehearsed talk will go much more smoothly than if you try to do it ad-hoc.
- Time your practice talk, the real talk itself will usually be a little longer.
- Keep focussed: what is the key point of your presentation?
- "Take home": what do you want the audience to remember from your presentation?
- Try not to read from notes, your audience can read a paper as well as anyone.
- If there is more than one presenter in a group, the others should step back whilst he/she is speaking. Do not continue to stand center-stage and glare angrily at the audience when someone else is speaking.
- Do not over-run. Time is usually very tight for presentations.
- Read: The Speaker's Guide.
- Speak slowly and clearly. Do not speak too quickly or mumble.
- Face the audience and make eye-contact with various members of the audience (not only the good-looking ones!). This is to show that you are actually addressing people and not just empty space.
- If you are using Powerpoint slides
- A time-tested rule of thumb is: 2 minutes per slide
- Avoid too much text per slide. If the audience has to spend a lot of time reading your slide, they will not concentrate on what you are saying.
- Avoid colours that produce eyestrain in your audience.
- Avoid unnecessary animations.
- If you are using a black-/white-board do not turn your back to the audience for too long.