Technical Writing

1. Technical Writing Effective Formatting

2. Effective communication is the goal. • Why write it if no one wants to read it? • Make life easy on the reader • Standard guidelines lead to consistent formatting • Consistent formatting leads to greater readability

3. Think in terms of the Golden Rule …what would you be more inclined to read? • A long document or a short one? • Filler and fluff or just what is necessary? • Pages filled from edge to edge or pages that include intentional white space? • Random thoughts or a logical progression? • Jargon that means nothing to you or terms that understandable? • Confusing discussion or clear explanations? • All words with no “pictures” or graphics that minimize the word count?

4. The purpose of having guidelines is to make the document more readable. • Written documents should adhere to standard guidelines. Such 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.

5. 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 • The amount of background information provided • Your use of technical terms (jargon) • The types of graphical items used • How data is presented • How data is discussed

6. 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? (Read this document about paragraph structure from the UCF Writing Center!) • Figures and tables should be placed to coincide with the associated text, unless otherwise directed. • Consistency in fonts, justification, numbering, etc. make the document more readable.

7. 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 description. (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.

8. 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.)

9. 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.)

10. Photos and drawings can communicate qualitative and quantitative information. • Photos and drawings are figures, so captions always go 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.

11. 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{fig3label}) • Table 1 (Table~\ref{tab1label}) • Section 3.2 (Section~\ref{sec32label}) • 10 meters • 47 k

12. 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

13. 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...” • 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 ...” • Recommendations and future work are given in future tense.

14. 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

15. 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

16. Plan. Outline. Draft. Revise. Proofread (self). Edit. Proofread (others). Edit. Submit. • Plan • see the previous 14 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

17. 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

18. Being a good steward of your time allows for maximum 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.