Technical Writing Form. The purpose of having guidelines is to make the document more readable....

46
Technical Writing Form

TAGS:

Transcript of Technical Writing Form. The purpose of having guidelines is to make the document more readable....

Page 1: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

Technical Writing

Form

Page 2: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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.

Page 3: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

Effective communication is the goal.

Make life easy on the reader!

Guidelines → Consistent Formatting → Readability

Page 4: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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

Page 5: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

GENERAL FORMATTING

The format of the document should help the reader.

Page 6: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

Margins and white space keep the reader from being overwhelmed.

Wall-to-wall text …NO white space!

Margins & white spaceGood white space!

Page 7: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

Headings and subheadings direct the reader’s attention.

Must have at least2 subsections.

Page 8: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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

Use paragraphs!Be intentional abouttopic sentences.

Page 9: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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

Be consistent!

Page 10: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

USING GRAPHICS (GENERAL)

The use of graphics can make or break a document!

Page 11: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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

Page 12: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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

Page 13: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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!

Page 14: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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

Page 15: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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.

Page 16: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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

Page 17: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

GRAPHS & CHARTS

Graphs and charts communicate quantitative information.

Page 18: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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

Page 19: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

Legends should only be included when necessary.

Page 20: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

Do NOT put frames around graphs and charts.

NO frames!

Page 21: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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

Page 22: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

Table captions always go above the table.

Page 23: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

Distill (i.e. trim down) data presented in tables.

Page 24: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

Row and column headings should be clearly labeled and set apart.

Page 25: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

Units should be specified.

Page 26: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

Use consistent formatting within a column. Use consistent formatting within a column.

Page 27: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

Think about the use of borders and color/shading. (Help the readers, don’t overwhelm them.)

Page 28: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

Photos and drawings are figures, so captions always go below the figure.

Page 29: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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

Page 30: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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

Lots of clutter

Page 31: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

“Drawings” should be of a professional nature.

Page 32: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

USING SPECIFIC REFERENCES

Page 33: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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!!!

Page 34: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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.

Page 35: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

WRITING STYLE

There are accepted standards for writing technical documents.

Page 36: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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

http://www.protrainco.com/essays/passive.htm
Page 37: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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

Page 38: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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

Page 39: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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

Page 40: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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

Page 41: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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

Page 42: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

GOOD WRITING REQUIRES EFFORT

Page 43: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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

Page 44: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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

http://pegasus.cc.ucf.edu/~uwc/Writing%20Resources/Handouts/concision_check.htm
http://www.lbcc.edu/WRSC/documents/WritingClearSent_AvoidAmbigTHIS.pdf
http://www.uwc.ucf.edu/files/handouts/Improving_Coherence_and_KnownNew_Contract.pdf
http://uwf.edu/writelab/handouts/documents/Paragraphcoherence.pdf
Page 45: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

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.

Page 46: Technical Writing Form. The purpose of having guidelines is to make the document more readable. Standard guidelines govern – Format – page layout, numbering.

Technical Writing

Form


Jane Eyre (Readable Classics)

Jane Eyre (Readable Classics)

Signalling Point Code Numbering Plan and Guidelines طﺎﻘﻧ ...

Signalling Point Code Numbering Plan and Guidelines طﺎﻘﻧ ...

Dissertation - Readable

Dissertation - Readable

FORMATTING READABLE OUTPUT

FORMATTING READABLE OUTPUT

Plant Numbering

Plant Numbering

Ainiakbari00jarrgoog Readable

Ainiakbari00jarrgoog Readable

Page Numbering

Page Numbering

Numbering System

Numbering System

Guidelines for IPv4 Addressing, AS Numbering for … Association Non-confidential Official Document IR.40 - Guidelines for IPv4 Addressing, AS Numbering for GPRS Network and Mobile

Guidelines for IPv4 Addressing, AS Numbering for … Association Non-confidential Official Document IR.40 - Guidelines for IPv4 Addressing, AS Numbering for GPRS Network and Mobile

Numbering Systems

Numbering Systems

Writing readable Clojure code

Writing readable Clojure code

Readable Perl

Readable Perl

HOUSE NUMBERING GUIDELINES 2017 - Kampala

HOUSE NUMBERING GUIDELINES 2017 - Kampala

Moby Dick (Readable Classics)

Moby Dick (Readable Classics)

CSS Guidelines (2.2.4) – High-level advice and guidelines ... · keep stylesheets maintainable; keep code transparent, sane, and readable; keep stylesheets scalable. There are a

CSS Guidelines (2.2.4) – High-level advice and guidelines ... · keep stylesheets maintainable; keep code transparent, sane, and readable; keep stylesheets scalable. There are a

Readable Asop v1

Readable Asop v1

Bunch Numbering

Bunch Numbering

SNN Policy and Procedure Guidelines - Moray · Part 1: The background to street naming and property numbering/naming Street naming and property numbering/naming is an important aspect

SNN Policy and Procedure Guidelines - Moray · Part 1: The background to street naming and property numbering/naming Street naming and property numbering/naming is an important aspect

PAGE DESIGN. I. Guidelines of Page Design 3 I. GUIDELINES DEFINITION: o Refers to the creation of clear, readable, and visually interesting documents.

PAGE DESIGN. I. Guidelines of Page Design 3 I. GUIDELINES DEFINITION: o Refers to the creation of clear, readable, and visually interesting documents.

Creating Readable Email Newsletters

Creating Readable Email Newsletters