Technical Writing

Form

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.

Effective communication is the goal.

Make life easy on the reader!

Guidelines → Consistent Formatting → Readability

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

GENERAL FORMATTING

The format of the document should help the reader.

Margins and white space keep the reader from being overwhelmed.

Wall-to-wall text …NO white space!

Margins & white spaceGood white space!

Headings and subheadings direct the reader’s attention.

Must have at least2 subsections.

Paragraphs…hmm…why is it that I have to remind students to use paragraphs? Think TOPIC SENTENCES!

Use paragraphs!Be intentional abouttopic sentences.

Consistency in fonts, justification, numbering, etc. make the document more readable.

Be consistent!

USING GRAPHICS (GENERAL)

The use of graphics can make or break a document!

Each graph/table/image should help achieve your ultimate purpose.

Figures and tables should be placed to coincide with the associated text, as space allows, unless otherwise directed.

Adhere to standard conventions for placement of graphics (usually centered at the top or bottom of a page).

The figure is at the top of the page!

All captions should be descriptive … 1-2 sentences is appropriate.

Every figure* and table should be referenced by name in the paper.

*Charts, graphs, photos, drawings, anything that isn’t a table.

These references are created usingautomated references in LaTeX.

Figures and tables should appear in the order they are referenced.

GRAPHS & CHARTS

Graphs and charts communicate quantitative information.

Graphs should be fully labeled – axes, units, descriptive titles – all with legible font sizes.

Legends should only be included when necessary.

Do NOT put frames around graphs and charts.

NO frames!

Think about the use of color … different line styles may be better than relying solely on different colors.

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. 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 are figures, so captions always go below the figure.

Make sure the readers will know what they’re viewing. Superimpose labels & arrows.

Pay attention to the contrast in the image, especially when it may be rendered in B & W.

Lots of clutter

“Drawings” should be of a professional nature.

USING SPECIFIC REFERENCES

Specific references to figures, tables, equations, and parts of a document 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: vol-vs-time})

– Table 1 (Table~\ref{tab: univdata})

– Section 3.2 (Section~\ref{sec: samplecalc})

The ~ inserts a space!

You have to type the words Figure or Table or Section!!!

Specific quantities help the reader.

Think in terms of referring to things by their full name – first and last.– 10 meters (10~meters)

– 47 k (47~k$\Omega$)

Notice the space between the # and the units!

The ~ prevents keeps the firstand last names on the sameline.

WRITING STYLE

There are accepted standards for writing technical documents.

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

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

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 …”

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

GOOD WRITING REQUIRES EFFORT

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

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

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.

Technical Writing

Form