Docstoc

technical_writing

Document Sample
technical_writing Powered By Docstoc
					Technical Writing


Dr Ted Burke
26/11/2008
Table of Contents
What  is good technical writing?
Plagiarism
Language and tone
Literature review
References and quotations
Creating a document
Drafting, editing and proof-reading
Figures, graphs, equations
Useful software
What is good technical writing?

   CLEAR, BRIEF and USEFUL
   It’s written to communicate
    technical information to the reader
   It’s not written to make the writer
    look clever (although it might)
   It’s contingent upon good content
    (no point writing eloquently about
    nonsense)
   It takes time and focus
Thoughts on Good Technical Writing
   A good technical document is of great value
   Smart readers return to good technical
    documents again and again
   The benefits of good technical writing are
    SCALABLE; a great document can be used and
    appreciated countless times by many readers.
   The act of good technical writing is:
       not just the gruelling slog of the last mile
       not just 50% of the 90% perspiration
       a useful, energizing creative process
   Today, "technical writing" should mean more than
    just writing – augment with relevant media
What about good "academic" writing?


   Firstly, it must be good technical writing
    in the general sense - i.e. not rubbish
    (see above)
   Bear assessment guidelines in mind
   Write for the intended audience, with
    appropriate content and level of detail
   Follow useful academic conventions - they
    are evolving, but remain in use for good
    reasons
Key Points / Tips
   Write CLEAR, BRIEF and USEFUL
    documents
   Write HONEST documents you can
    stand over
   Presentation is important - pay
    attention to detail, but…
   Keep sight of the bigger picture -
    focus on what's important
   Read plenty of good documents
Plagiarism
   “Plagiarism is the practice of
    claiming or implying original
    authorship of (or incorporating
    material from) someone else's
    written or creative work, in whole or
    in part, into one's own without
    adequate acknowledgement.”
    Source: Plagiarism. (2008, May 30). In Wikipedia,
    the free encyclopedia. Retrieved June 3, 2008, from
    http://en.wikipedia.org/wiki/Plagiarism
Language and Tone
What NOT to do:

“I thought that the device might work
   better if I tightened up the screws a bit. I
   went to the shop to get the right
   screwdriver then when I came back, my
   superviser told me it was ok to try that.
   But when we tightened them, the plate
   was on to tight and the roter got broke so
   I had to spend a month rebuilt the rotor
   and plate, so a good bit of time was
   waisted unfortunately.”
Language and Tone
Avoid first person references (“we”, “I”, etc)

“I thought that the device might work
   better if I tightened up the screws a bit. I
   went to the shop to get the right
   screwdriver then when I came back, my
   superviser told me it was ok to try that.
   But when we tightened them, the plate
   was on to tight and the roter got broke so
   I had to spend a month rebuilt the rotor
   and plate, so a good bit of time was
   waisted unfortunately.”
Language and Tone
Check your spelling. Seriously, check it!

“I thought that the device might work
   better if I tightened up the screws a bit. I
   went to the shop to get the right
   screwdriver then when I came back, my
   superviser told me it was ok to try that.
   But when we tightened them, the plate
   was on to tight and the roter got broke so
   I had to spend a month rebuilt the rotor
   and plate, so a good bit of time was
   waisted unfortunately.”
Language and Tone
Check your grammar and punctuation:

“I thought that the device might work
   better if I tightened up the screws a bit. I
   went to the shop to get the right
   screwdriver then when I came back, my
   superviser told me it was ok to try that.
   But when we tightened them, the plate
   was on to tight and the roter got broke so
   I had to spend a month rebuilt the rotor
   and plate, so a good bit of time was
   waisted unfortunately.”
Language and Tone
Avoid casual, vague language:

“I thought that the device might work
   better if I tightened up the screws a bit. I
   went to the shop to get the right
   screwdriver then when I came back, my
   superviser told me it was ok to try that.
   But when we tightened them, the plate
   was on to tight and the roter got broke so
   I had to spend a month rebuilt the rotor
   and plate, so a good bit of time was
   waisted unfortunately.”
Language and Tone
Don’t just tell the story of what you did:

“I thought that the device might work
   better if I tightened up the screws a bit. I
   went to the shop to get the right
   screwdriver then when I came back, my
   superviser told me it was ok to try that.
   But when we tightened them, the plate
   was on to tight and the roter got broke so
   I had to spend a month rebuilt the rotor
   and plate, so a good bit of time was
   waisted unfortunately.”
Language and Tone

“Initial tests showed that the device was running at a
  lower speed than it had been designed to do,
  probably due to unintended, but clearly visible
  vibration of the rotor. To reduce this vibration, the
  screws holding the cover plate in place were firmly
  hand tightened. Unfortunately, this was done while
  the machine was running and the tightening caused
  the centre of the cover plate to flex inwards,
  bringing it into contact with the spinning rotor. This
  caused serious damage to the rotor and plate,
  requiring time-consuming re-fabrication of both
  parts.
To address the original vibration problem, additional
  anchor points between the stator, chassis and cover
  plate were added. Furthermore, to avoid any
  possible recurrence of contact between the spinning
  rotor and the cover plate, the clearance between the
  two was increased by 5mm.”
References
   Several different styles: IEEE, APA, etc.
    Pick one, look up detailed instructions on
    it and adhere strictly to them.
   Provide a reputable, authoritative
    reference for any fact on which you rely
    unless it is completely self-evident.
   All items in your list of references should
    usually be cited in your main text.
   Make sure your references are detailed
    and accurate. Most importantly, could
    somebody find what you read from your
    reference? If not, it’s inadequate.
Reference example
“Several existing ambulatory BCI prototypes
   exist [3, 4], but the system described in
   the current paper is the first such non-
   invasive one.”

3.   R.V. Weinmann and M.J. Schroeder. A
     microcontroller-based ambulatory brain-
     computer interface training system. In
     Proceedings of the 25th Annual
     International Conference of the IEEE
     Medicine and Biology Society, 2003, vol.
     3, pages 2204- 2207. 17-21 September
     2003.
Quotations: In-text example


Burke [6] describes plagiarism as “the
 single biggest threat to academic
 integrity in modern institutes of
 higher education”, and goes on to
 advocate an uncompromising hard-
 line disciplinary regime.
Quotations: Block example

Burke [6] describes plagiarism as follows,

    “Plagiarism is the single biggest threat to
    academic integrity in modern institutes of
    higher education. The only defence against its
    undermining influence is a policy of ruthless,
    hard–line discipline.”

This attitude is shared by many of the
  foremost modern thinkers in the field.
 Starting a document

    Get document specs at the outset (format, length, etc)
    If possible, ask to see previous successful submissions
    For an assignment or research proposal, get info on
     marking scheme and/or assessment guidelines
    Choose the right software and stick with it
    Learn to use section numbering, cross-referencing, etc
    Learn to use a maths editor (e.g. Equation Editor)
    When faced with a blank page...

          Sit down and start writing even if you
           can’t think of anything better than:

“In recent years, <WHATEVER> has
become an increasingly important…”
(Typical) Dissertation structure
   Abstract
   Introduction
   Literature review
   Implementation / details of experiment
   Test / experimental results & analysis
   Conclusion
   References
   Appendices
    It’s not a whodunit - disclose complete story in abstract.
        Intro and conclusion should read well in isolation.
Some Notes
   The abstract is most important part
   The introduction and conclusion are crucially important
   Remember that the reader may (quite legitimately) be
    skimming your document

     I used to say "Nobody spends as much time reading
      your document as you spend writing it," but then I
      realised that I was spending more time correcting
           some rubbish than was spent "writing" it.
   If you're a careful writer (or a perfectionist), focus on
    what’s most important (see above).
   If you're a lazy, sloppy writer, please change.

         Either way, think about the reader and the
    circumstances in which he or she will be reading it.
Figures (illustrations, graphs, etc)

   Figures should be self-contained
   Figures should be clearly labelled
   Figures should have a clear caption
   All figures should be referenced in
    the main text
Figures (illustrations, graphs, etc)
   Master one or two good drawing tools
    (one raster, one vector)
       Inkscape/Gimp
       Paintshop/Illustrator
   Accumulate good images
       Take lots of photos / videos
       Sketch diagrams in a notebook (to be redrawn
        later)
       Use the "Print Screen" button
       Archive your images for later editing / reuse
Graphs

   Make sure your graph makes sense
    in isolation from the text.
   Are your axes labelled?
   Are the units shown?
   Are relevant features labelled?
Equations

   Use equation editor or an equivalent
    tool to produce professionally
    formatted equations. Do it!!!
   Number equations where relevant
    so that they can be referenced in
    the text.
   Make sure the equations are
    accurate.
Drafting, editing and proof-reading

   Plan time to edit and proof read the
    document
   Writing should be an iterative
    process: draft, edit, draft, edit…
    …proof-read, have it proof-read,
    polish, submit.
   Don't ask readers / supervisors to
    read rubbish
Useful software

   MS Word, OpenOffice, LaTeX
   References: Zotero, Endnote
   Equations: MS Equation Editor, TeX
   Images: GIMP, Photoshop
   Diagrams: Inkscape, Illustrator
   Circuit diagrams: LT Spice
   Graphs: MATLAB, MS Excel
Check List: Style and content
   Above all else: Avoid plagiarism! Have
    you correctly acknowledged your sources
    for all text, images, etc?
   Is the language and tone appropriate?
   Would what you have written look strange
    in a text book or academic paper? If so,
    the style is probably wrong.
   Have you included adequate references to
    support all your statements?
   Are your references and quotations
    formatted correctly and consistently?
Check List: Figures, graphs, equations

   Are your figures self-contained?
   Have you referred to all your figures in
    the text?
   Are your graphs correctly labelled?
   Do all your graphs have an appropriate
    title and/or caption?
   Are the units shown in your graphs?
   Are your equations accurate and legible?
   Are your equations numbered?
Check List: Editing and Polishing
   Have you carefully read and re-read every page
    of your finished document?
   Have you got someone else to proof-read your
    document, both for errors and overall clarity of
    communication?
   Have you asked what could make your document
    easier to understand?
   Have you carefully spell-checked your document?
   Have you asked for feedback prior to submission?
   Have you included all required components –
    abstract, conclusions, references, etc?
   Have you presented it appropriately? For
    example, is it properly bound or in the correct file
    format?
General Tips
   To do good writing, you need to "get in
    the zone"
   To "get in the zone" you need to be
    writing
   Backup your work!!!! Email documents
    and source materials to your web mail
    account if you have one
   Do not be one of the people that
    complains that you "lost everything" -
    everyone's heard that one before and
    they're sick of it