EM Lab Meeting -- Technical Writingemlab.utep.edu/pdfs/Technical Writing.pdf · Technical writing is hard work. There is no shortcut through it. You can only save yourself time by

Pioneering 21st Century Electromagnetics and Photonics

Technical Writing

Raymond C. Rumpf, Ph.D.(915) 747-6958

[email protected]://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.

Outline

• Checklists• Steps to Technical Writing• Other Advice

3/23/2016 Technical Writing Slide 3

Checklists

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

Steps toTechnical Writing

Step 1 – You Have Something to Write About


Some nugget of your research must have come to a conclusion that is important to share to the community.

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.

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?

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?

Step 5 – Make an Outline


Create a high level outline that will 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.

If a section has no bullets, it should not be a section.

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.

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.

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.

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.

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.

Step 10 – Spell Check and Grammar Check


This is an easy-to-forget step, but is very important.

Sloppy documents are evaluated more poorly.

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!

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 message3. Spelling, grammar,

and wording mistakes.

Have your buddy complete the checklists as well.

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.

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.

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.

Other Advice

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?

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

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.

Documents

EM Lab Meeting -- Technical Writingemlab.utep.edu/pdfs/Technical Writing.pdf · Technical writing is hard work. There is no shortcut through it. You can only save yourself time by