Download Report

4/2/2015
Pioneering 21st Century
Electromagnetics and Photonics
Technical Writing
Raymond C. Rumpf, Ph.D.
(915) 747-6958
[email protected]
http://emlab.utep.edu
Technical writing is hard work.
There is no shortcut through it.
You can only save yourself time
by doing it right the first time.
You will get better and faster with
practice.
1
4/2/2015
Outline
• Checklists
• Steps to Technical Writing
• Other Advice
4/2/2015
EM Lab
Slide 3
Checklists
2
4/2/2015
Purpose of the Checklists
The checklists are intended for you to work
through in order to make sure that you have
considered everything that is important to
generate quality technical documents and
graphics.
http://emlab.utep.edu/academics.htm
4/2/2015
EM Lab
Slide 5
Steps to
Technical Writing
3
4/2/2015
Step 1 – You Have Something
to Write About
Some nugget of your research much have come to a conclusion
that is important to share.
4/2/2015
EM Lab
Slide 7
Step 2 – You Must Be an Expert
On Your Topic
To be an expert, you must have performed a comprehensive
literature search so you are aware of the state-of-the-art and
what your contribution is.
4/2/2015
EM Lab
Slide 8
4
4/2/2015
Step 3 – What Are You Writing
and Who is the Audience?
Are you writing a journal article, a customer report, a poster, a
presentation, etc.?
Are you writing to members of the EM Lab, to your Ph.D.
committee, the general public, to first graders, to other
engineers/scientists?
4/2/2015
EM Lab
Slide 9
Step 4 – Read and Archive All
Requirements
Are you required to write about a specific topic?
Are you required to follow a specific outline?
Are you required to have specific formatting?
Is anything else required?
4/2/2015
EM Lab
Slide 10
5
4/2/2015
Step 5 – Make an Outline
Create a high level outline
that will likely become your
section headings.
Make a bullet list in each
section to identify the key
points you need to make in
that section.
Review the outline for a
logical flow of information
and no redundancy.
4/2/2015
Abstract – A very brief summary of your document
written in simple layperson language.
Introduction – What is your topic? Why is it
important? What have others done in this area?
What is your unique contribution? How is your
document organized to explain what you have
done?
Background – Discuss topics the reader needs in
order to understand your document? Usually no
need to discuss topics common in the literature.
Body – The bulk of your document. Well-organized
and methodical description of your topic(s).
Discuss your procedures, present your results,
draw conclusions, explain anomalies. Sufficient
detail must be presented for the reader to
reproduce your work.
Conclusion – Why did you do? Why is it
important? What new results did you generate?
What meaningful conclusions were drawn from your
results? Outline future work.
EM Lab
Slide 11
Step 6 – Write the Introduction
Write the introduction first. This sets the stage for your entire
document and will help you focus on the central message.
•
•
•
•
•
Introduce your main topic.
Discuss why it is important.
Discuss the history and what others have done on this topic.
Introduce what you did and why your approach is unique and useful.
For large documents, consider adding a paragraph to outline how
your document is organized.
4/2/2015
EM Lab
Slide 12
6
4/2/2015
Step 7a – Write the Body
You will spend the majority of your time writing the body.
Present your topics in a logical and well-planned order. Read
similar documents for inspiration on how to organize.
•
•
•
•
Describe your procedures.
Present your results.
Draw conclusions and discuss them.
Explain anomalies.
Say it once. Say it well.
Don’t say it again.
Don’t include meaningless messages or
graphics. Include those in an Appendix if
you really want to.
4/2/2015
EM Lab
Slide 13
Step 7b – Sketch Figures First
Write all the way up until you need to insert a figure.
Roughly sketch the figure on paper.
Revise the figure as you write the discussion of the figure. This will give
better consistency and will more clearly convey the message to reader.
Create the figure from your sketch with great care and attention to detail.
4/2/2015
EM Lab
Slide 14
7
4/2/2015
Step 9 – Write the Abstract
The abstract is a self-contained and short description of your
technical document.
Without sounding awkward, include
as many key words and buzz words
as possible.
4/2/2015
EM Lab
Slide 15
Step 10 – Spell Check and
Grammar Check
This is an easy-to-forget step, but is very important.
Sloppy documents are evaluated more poorly.
4/2/2015
EM Lab
Slide 16
8
4/2/2015
Step 11 – Proofread Your Own
Document
Put your document aside if you have time. Proof it a few days or
a week later.
Read it aloud. You are more likely to catch mistakes this way.
Make three passes:
1. Spelling, grammar, and wording
errors.
2. Formatting and graphics.
3. High level message.
Be sure your document passes
the checklists!
4/2/2015
EM Lab
Slide 17
Step 12 – Buddy Review
Have your document reviewed by somebody not intimately
aware of your research.
Have the buddy make three passes:
1. Formatting, cleanliness, and professionalism.
2. High level message
3. Spelling, grammar,
and wording mistakes.
Have your buddy
complete the checklists
as well.
4/2/2015
EM Lab
Slide 18
9
4/2/2015
Step 13 – Revise Document
Revise your document based on buddy’s feedback.
Make a quick pass through the revised document to ensure
consistent formatting and that no
graphics or tables jumped around
leaving awkward white space.
If the revisions were significant enough,
go back to Step 10 and start the review
process again from the beginning.
4/2/2015
EM Lab
Slide 19
Step 14 – Help with English
Consider using the university Library resources to help ensure
proper English.
To not waste the Library’s time, be
sure document is as good as you can
make it before taking it to them.
4/2/2015
EM Lab
Slide 20
10
4/2/2015
Step 15 – Submit to Dr. Rumpf
The last step is to submit to Dr. Rumpf.
Dr. Rumpf will by far be your harshest reviewer.
Because he cares. Really. 
Dr. Rumpf while reviewing technical
documents from his students.
4/2/2015
EM Lab
Slide 21
Other Advice
11
4/2/2015
Proofreading
Proofreading is a unique and important skill.
You will have a much more objective perspective about the
technical document than the writer does.
• Is the overall message clear and stated right upfront?
• Does the document have a consistent, clear, and
professional format?
• Is the document easy to use?
• Are the graphics clear?
• Are the descriptions easy to understand?
• Is the document complete?
4/2/2015
EM Lab
Slide 23
Version Control
It is best to save your documents with a version number at the
end of the file name.
Customer Report Feb 2015 v1.docx
Create a new version when:
1. Revisions are significant.
2. You may want to resort back to a prior version.
When editing somebody else’s document, add your name or
initials to the end of the file name.
Customer Report Feb 2015 v1 RCR.docx
4/2/2015
EM Lab
Slide 24
12
4/2/2015
Best Practices for Editing
Learn how to use “Track Changes” and Comments in MS
Word.
Make edits on written documents visible and obvious.
Be helpful and specific. Avoid saying vague things like “reword
this.” Instead, reword the text for the writer.
Don’t just highlight mistakes, fix them.
Review the Tables and Figures in addition to the text.
4/2/2015
EM Lab
Slide 25
13