Technical Writing

1. Technical Writing Form

2. Effective communication is the goal. Make life easy on the reader! Guidelines → Consistent Formatting → Readability

3. The purpose of having guidelines is to make the document more readable. Standard guidelines govern • Format – page layout, numbering conventions, etc. (the reason we use LaTeX) • Graphics – use of figures, graphs, charts, tables • Voice – appropriate use of active and passive voice • Verb tense – appropriate for and consistent within each section • References & citations – giving appropriate credit Technical documents have different guidelines than other forms of writing.

4. As you are planning the document, keep the background of your audience in mind. • Do they have a technical background? • Are they knowledgeable on your subject? • Their background should impact • Amount of background information • Use of technical terms (jargon) • Types of graphics • How data is presented • How data is discussed

5. The format of the document should aid the reader. • Margins and white space keep the reader from being overwhelmed. • Headings and subheadings direct the reader’s attention. • Paragraphs…hmm…why is it that I have to remind students to use paragraphs? Think TOPIC SENTENCES! • Figures and tables should be placed to coincide with the associated text – as space allows, unless otherwise directed. • Consistency in fonts, justification, numbering, etc. make the document more readable.

6. The use of graphics can make or break a document. • Each graph/table/image should help achieve your ultimate purpose. • Adhere to standard conventions for placement (usually centered at the top or bottom of a page). • All captions should be descriptive. (1-2 sentences is appropriate.) • Every figure* and table should be referenced by name in the paper. • Figures and tables should appear in the order they are referenced. *Charts, graphs, photos, drawings, anything that isn’t a table.

7. Graphs and charts communicate quantitative information. • Figure captions always go below the figure. • Graphs should be fully labeled – axes, units, descriptive titles – all with legible font sizes. • Legends should only be included when necessary. • Avoid using frames around graphs and charts. • Think about the use of color. (Different line styles may be better than relying on different colors.)

8. Tables communicate quantitative information. • Table captions always go above the table. • Distill (i.e. trim down) data presented in tables. • Row and column headings should be clearly labeled and set apart. • Units should be specified. • Use consistent formatting within a column. • Think about the use of borders and color/shading. (Help the readers, don’t overwhelm them.)

9. Photos and drawings can communicate qualitative and quantitative information. • Photos and drawings are figures, so captions alwaysgo below the figure. • Make sure the readers will know what they’re viewing. Don’t assume that something you’ve looked at a million times will be clear to them. • Pay attention to the contrast in the image, especially when it may be rendered in B & W. • Superimpose labels & arrows, when needed. • “Drawings” should be of a professional nature.

10. Specific references to parts of a document and specific quantities help the reader. • References to figures, tables, sections, and equations must be automated (using the ~\ref{} command in LaTeX). • Think in terms of referring to things by their full name – first and last. • Figure 3 (Figure~\ref{fig: fig3label}) • Table 1 (Table~\ref{tab: tab1label}) • Section 3.2 (Section~\ref{sec: sec3-2label}) • 10 meters (10~meters) • 47 k (47~k$\Omega$) Notice the space between the # and the units!

11. The voice should place proper emphasis. • Active voice emphasizes the actor. • Passive voice emphasizes the action. • It is okay to have a mix of both…just know when each is appropriate! • http://www.protrainco.com/essays/passive.htm

12. The verb tense should correspond to the subject matter. • Use the past tense when talking about the experiment or work that has been completed. • “The objective of the experiment was...”

13. The verb tense should correspond to the subject matter. • The report, the theory, the results, and the permanent equipment still exist; therefore, these are referenced in the present tense: • “The purpose of this report is...” • “Bragg's Law for diffraction is ...” • “The results show …” • “The scanning electron microscope produces micrographs ...”

14. The verb tense should correspond to the subject matter. • Recommendations and future work are given in future tense. • “The next phase of the project will involve …”

15. Proper citations are key to maintaining credibility. • Cite sources whenever you are quoting, paraphrasing, or summarizing work that is not your own • Quoting directly is discouraged • Sources include: • Books • Journal, magazine, or newspaper articles • Interviews • Conference Proceedings • Lectures • Websites

16. Proper citations are key to maintaining credibility. • Shows your credibility as a researcher • Gives proper credit to authors and researchers • Protects you from accusations of plagiarism • Bibliography formats • Various styles • Can include only cited references or all references • Citations in LaTeX done with \cite{} command

17. Plan. Outline. Draft. Revise. Proofread (self). Edit. Proofread (others). Edit. Submit. • Plan – see the previous 15 slides • Outline – see the “Reporting the Outcome” handout (Dym & Little) • Draft & Revise – also known as writing  • Proofread – see the following slide • Edit – correct problems found during proofreading

18. The proofreading process can make a huge difference in effectiveness (and in your grade). • Proofread for • Big picture understanding • Spelling errors • Conciseness (concision checklist) • Grammar errors (subject-verb agreement & punctuation) • Verb use (appropriate tense, consistent tense w/in sections, use of active and passive voice) • Ambiguity (avoiding ambiguous words) • Sentence coherence (checking sentence coherence) • Paragraph coherence (checking paragraph coherence) • Sectional coherence

19. Be a good steward of your time and maximize your effectiveness and growth as a writer. • Start early. • Plan your document. • Make use of tools like the Topic-Sentence Outline. • Find good proofreaders and give them time to be thorough. • Incorporate the proofreaders’ feedback. • Don’t view submission of the paper as the end of the assignment.

20. Technical Writing Form