Technical Writing

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

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?

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.

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

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!)paragraph structure 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.

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.

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

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

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.

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 

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!

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.

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

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

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

The proofreading process can make a huge difference in effectiveness (and in your grade). Proofread for –Big picture understanding –Spelling errors –Conciseness (concision checklist)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)avoiding ambiguous words –Sentence coherence (checking sentence coherence)checking sentence coherence –Paragraph coherence (checking paragraph coherence)checking paragraph coherence –Sectional coherence

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.