Technical Writing and Documentation Practices

Podcast

Play an AI-generated podcast conversation about this lesson

Questions and Answers

What is the primary purpose of using visuals in documentation?

To fill empty spaces in the layout

To add decorative elements to enhance aesthetics

To provide clarity and support the information presented (correct)

To present complex data in a confusing manner

What should be done before a visual appears in a document?

Add a brief description of its colors

List it in the table of contents

Mention it in the text to prepare the reader (correct)

Create a detailed history of its creation

Why is it important to consider grayscale representation of visuals?

Color is necessary to convey intricate information

All visuals should be colorful for impact

Grayscale ensures visuals are clear for all audiences (correct)

Most people prefer colored visuals over black and white

Which of the following should be avoided when creating visuals?

Using 3-D charts when unnecessary Signup and view all the answers

What is the first step in the preparation phase of team writing?

Form the team Signup and view all the answers

Which type of writing is characterized by its reader-centered approach?

Technical Writing Signup and view all the answers

What is NOT a type of procurement document?

Scientific Report Signup and view all the answers

Which document is considered a type of software documentation?

Installation Guide Signup and view all the answers

Which phase involves understanding the audience and defining the purpose of the writing?

Preparation Phase Signup and view all the answers

In which type of academic writing would you typically find a comprehensive review of existing literature?

Review Articles Signup and view all the answers

Which of the following is an example of a technical writing genre?

Memo Signup and view all the answers

What should be avoided when engaging in professional communication?

Using slang Signup and view all the answers

What is an effective proofreading strategy to enhance accuracy?

Read text slowly and out loud Signup and view all the answers

Which of the following is NOT a recommended proofreading technique?

Use tools like Grammarly without any checks Signup and view all the answers

How can changing the format of a document assist in proofreading?

It can help in identifying errors by providing a fresh perspective Signup and view all the answers

What does the author imply about homonym errors in spelling?

They are often missed by computer spell check tools Signup and view all the answers

According to the author, how can punctuation misuse affect a writer?

It can obscure and confuse the audience Signup and view all the answers

What is the purpose of using bullets when writing?

To present instructions or tasks clearly Signup and view all the answers

How is effective communication evaluated in technical writing?

By identifying the 4 out of the 7Cs and addressing them Signup and view all the answers

Which of the following is a correct spelling comparison between British and American English?

The spelling of 'color' in British English is 'colour' Signup and view all the answers

What is the significance of reading paragraphs in reverse order while proofreading?

It directs attention away from the content's flow to highlight errors Signup and view all the answers

What component generates the electrical charge necessary for igniting the fuel-air mixture?

Spark plug Signup and view all the answers

What is the result of the rapid burning of the fuel-air mixture in the piston assembly?

It produces exhaust gases occupying 2000 times the original volume. Signup and view all the answers

Which stroke follows the compression stroke in the operation of the piston assembly?

Power stroke Signup and view all the answers

What percentage of learning is derived from visual stimuli, according to the provided information?

83% Signup and view all the answers

What type of visual is NOT mentioned as a means of communicating information?

Sculptures Signup and view all the answers

Which component is primarily responsible for converting the downward movement of the piston into rotational motion?

Cam shaft Signup and view all the answers

What is the primary purpose of using visuals according to the information provided?

To enhance memory retention Signup and view all the answers

How should symbols be formatted when used in equations as per the guidelines?

Variables should be italicized, but numerals should not. Signup and view all the answers

What is the first stroke in the piston assembly's operational cycle?

Intake stroke Signup and view all the answers

Which of the following is an advantage of using visuals in documents?

They enhance the logical flow of information. Signup and view all the answers

What is the rule for capitalizing proper nouns in the context provided?

Capitalize names of religions and proper nouns Signup and view all the answers

Which sentence demonstrates a correct example of a sentence fragment?

Testing the specimen carefully with high levels of precision. Signup and view all the answers

Which voice is generally preferred for writing in lab reports?

Passive voice for focusing on actions Signup and view all the answers

How should the verb agreement be correctly structured in the sentence regarding implants?

The implant, along with its associated circuits, was inserted into the patient’s chest cavity. Signup and view all the answers

What does the sentence 'Each person in the lab must replace their radiation badge' illustrate?

Acceptance of plural pronouns for individuals Signup and view all the answers

What is one common reason for capitalizing titles?

When referencing historical documents Signup and view all the answers

What issue does the sentence 'Ignorance of science is a phenomenon in society that must be destroyed' present?

Misplaced modifier error Signup and view all the answers

Which of the following statements is true regarding capitalization rules?

The first word of every sentence must be capitalized. Signup and view all the answers

Which option best demonstrates a correct use of a modifier?

Broken by the storm, the lamp sat shattered. Signup and view all the answers

What type of error is represented in the sentence 'The implant, along with its associated circuits, were inserted into the patient’s chest cavity'?

Subject-verb agreement error Signup and view all the answers

Study Notes

Egyptian God Thoth

Thoth was the Egyptian god of writing, wisdom, and magic.
He advised and mediated for the gods.
He was the patron of scribes.
His female counterpart was Seshat, the goddess of writing and keeper of books.
Thoth created language.
Seshat gave Thoth's words to the people.

Technical Communication

Communication is the transfer of information.
Technical communication is the transfer of technical information.
The four basic communication modes are listening, speaking, reading, and writing.
Verbal communication involves speaking and listening.
Non-verbal communication involves writing and reading.

Characteristics of Technical Communication

Technical communication is precise, accurate, well-documented, and non-abstract.
It uses numerical data and relies heavily on visuals like equations, photographs, tables, graphs, and drawings.
It is always technically and stylistically correct.
It considers the audience, purpose, and context.

Audience Analysis

To analyze an audience, consider their previous knowledge, needed background, motivation, and required level of detail.

Purpose Analysis

The purpose of technical communication may be to understand facts, how something works, project status, to acquire funding or assemble something.
It could involve accepting recommendations, changing opinions or making decisions.

Context Analysis

Context includes history, language, geography, politics, culture, and economics.
It includes anything that affects how the audience receives communications.
Context is largely outside the writer's control and often needs to be clearly introduced.

Types of Technical Verbal Communication

One-on-one discussion
Team meetings
Public communication
Presentations (verbal with visual aids)

Types of Technical Writing

Reports
Proposals
Instructions manuals
Style sheets
Technical specifications
Technical standards
Software documentation
Troubleshooting guides
Emails
Memos
Technical Fliers
Press Releases
Standard operating procedures
White papers and case studies
Procurement documents
Academic Writing

Types of Procurement Documents

Request for information (RFI)
Request for Proposal (RFP)
Request for Quotation (RFQ)
Invitation for bid (IFB)
Sales proposal (SP)
Purchase and sales agreement (PSA)
Purchase order (PO)

Types of Academic (Scientific) Writing

Original research articles
Review articles
Case reports
Grant proposals
Scientific reports
Dissertations and theses

Types of Software Documentation

System architecture diagrams
Design documents
Source code comments
Application programming Interface (API) documentation
Installation guides
Release notes
Testing plans and reports

Activity 0 (General Guidelines of Professional Communication)

Using proper language is crucial for professional communication.
Avoid using Arabic-language words with English digits or letters, and vice versa.

Activity 1 (Document Analysis)

Upload a technical document of any type (or a link).
Identify the intended audience.
Identify the intended purpose.

Process of Document Writing

Start by writing a draft of the report.
Get feedback from peers.
Edit/modify the draft.
If the document is good, end the process. Otherwise, repeat the process.

Preparation Phase

Study the audience
Define the purpose
Identify the context
Choose the communication genre

Audience-Centred Writing

Writing should be reader-centered, focusing on benefiting the reader.
Conduct a formal or informal audience analysis prior to writing.

Audience Categories

Primary target audience
Secondary target audience
Tertiary target audience

Audience Characteristics

Job responsibility
Professional experience
Reading skills
Education
Cultural characteristics
Personal characteristics
Personal preferences

Audiences Attitudes and Expectations

Attitude towards the writer
Attitude toward the subject
Expectations about the document

Audience Profile Sheet

A form to gather various audience characteristics, used for planning communication. (includes detailed example for a manager)

Know about your Audiences

Determine what you already know about your audience,
Interview individuals,
Review online and social media content related to them,
Review documents written by your audience.

Purpose: To Inform

Authorize
Define
Describe
Explain
Illustrate
Inform
Outline
Present
Review
Summarize

Purpose: To Persuade

Analyze
Argue
Assess
Conclude
Determine
Evaluate
Forecast
Propose
Recommend
Request

Elements determined after analyzing audience, purpose, context, and genre

Amount of content required
Level of detail needed
Structure of the document
Format of the document
Tone to adopt
Style to employ
Length of each element

Genre Definition

A genre is a socially agreed-upon, recognized form of communication consistently used and developed by people over time to communicate effectively between each other.

Genre=Format+Structure

Genre = format * structure
Format is the visual or spatial design of the document (e.g. template)
Structure is the logical order of topics

Checking Document Output

Any technical communication genre must be checked before release.
Proofreading includes checking the content, elements, structure, and clarity.
Proofreading also involves checking errors in spelling, typos, grammar, and punctuation.

Editing: 7Cs of Effective Communication

Complete: Providing all necessary info for decisions.
Clear: Ensures message is easily understood without ambiguity
Concise: Conveying message with brevity without unnecessary details
Concrete: Using specific facts and evidence for credibility and believability
Coherent: All points are connected logically and the text flows consistently
Correct: Ensure accuracy in grammar, spelling, punctuation, and factual information
Courteous: Showing respect, politeness, and professionalism

Proofreading Strategies

Take a break (wait 2 hours or 2 days)
Proofread for one error at a time or read the text out loud
Use tools (e.g., spellcheck, Grammarly, Hemingway) but do not only rely on them.
Change format
Reduce window width, change font, print, cut and paste from one software to another
Read paragraphs in reverse order
Circle punctuation errors

Activity 2 (Communication Analysis)

Upload a technical document of any type (or a link).
Identify four out of the 7Cs of effective communication.
Evaluate how well the document addresses these elements.

Technical Writing Mechanics

Spelling: Accurate and correct spelling of words.
Punctuation: Correct use of punctuation marks.
Capitalization: Correct use of capital letters.
Grammar: Correct sentence structure and use of verb tenses.

Types of Spelling Errors

Substitution: Replacing words
Omission: Missing words
Insertion: Extra words
Transposition: Reordering words

Data on Spelling Errors (Example)

Substitution: 39.8%
Omission: 43.2%
Insertion: 10.5%
Transposition: 6.2% Typographical Errors (Example)
Homonyms are commonly misspelled errors.

Types of Spelling Issues (Continued)

Comparing American and British English: Differing spellings—color/colour, gray/grey, labor/labour.
Spelling Numbers correctly: 32 is the freezing point of water.
Exact numerals and number sequencing

Punctuation

Lynne Truss (author of "Eats, Shoots, and Leaves") describes punctuation as essential traffic signals in language.
Misusing punctuation can obscure, confuse, and mislead the reader.
Separates items in a series, options, or clauses.
Introduces additional information about a sentence topic.
Punctuation can divide words, connect words, and combine words.

Containers of Punctuation

Quotation marks—enclose direct quotations
Parentheses—contain additional/incidental information
Brackets—used as a second level of parentheses, often containing editorial corrections

Terminators

Period: Used for sentences that aren't questions or exclamatory statements.
Question mark: Used for interrogative sentences.
Exclamation point: Used for exclamatory sentences.

Indicators

Apostrophe: Indicates possession or omits certain words or letters
Ellipsis: Indicates omitted material

Paragraphs/Bullets

Paragraphs connect ideas, and logic, guiding the reader to a conclusion
Bullets—used to list unrelated information or instructions requiring sequential ordering

Capitalization

Follow required stylistic guides. Avoid random capitalization.
Capitalize the first word of every sentence.
Capitalize proper nouns.
Capitalize titles of books, films, programs, etc.

Grammar: Sentence Fragments

Testing the specimen carefully with high levels of precision is necessary.
Because the transformer could take the load the system quickly failed

Grammar: Misplaced Modifiers

Ignorance of science is a phenomenon in society that must be destroyed.
In society, ignorance of science is a phenomenon that must be destroyed.

Grammar: Active & Passive Voices

Active Voice generally makes writing stronger, more direct, and more active.
Passive voice is often preferred in technical writing, typically for lab reports or scientific research papers (especially in Materials and Methods).

Grammar: Verb Agreement Errors

The implant, along with its associated circuits, was inserted into the patient's chest cavity.
The implant and its associated circuits were inserted into the patient's chest cavity.

Grammar: Pronoun Agreement

Each person in the lab must replace their radiation badge.

Grammar: Pronoun Reference Errors

The coolant leak impaired the CPU’s heat dissipation, resulting in an erroneous reading at the most critical point in the process. This coolant leak had a cascading effect on the system

Grammar: Pronoun Case Errors

I hit myself with my tennis racket.

Grammar: Noun Clauses

The supervisor decided who would go to the conference.

Grammar: Compound Adjectives/Adverbs

We have on-site support.
Jane is a part-time employee. (Pre-noun modification)
We have support on site.
Jane works part-time (Post-noun modification)

Grammar: Phrasal Verbs

Get the plane
Get on the plane
We break the costs
We break down the costs

Grammar: Parallel Construction

By the operators, Safety protocol is implemented, Savings is $5 million/year.

Visual Aids

Why use visuals?
Types of visuals
General guidelines & considerations

Why Use Visuals?

Visuals assist with comprehension
Enhance the viewer's understanding
Visuals assist remembering information
Visuals can enhance the document readability by communicating steps or procedure
Conserve space in a document.

Types of Visuals

Equations
Chemical formulas
Diagrams
Graphs
Schematics
Tables
Images
Typographies

Equations

Represent relationships between expressions, using symbols and terms.
Symbols are italicized.
Text should use clear, concise language
Equation numbers included in a bracket

Chemical Formulas

Symbolic representation of molecules and chemical reactions.
Use of equal signs or arrows.

Diagrams

Explain systems, steps of a process, and relationships between components
Make them as simple as possible.

Graphs

Charts or plots for statistical data; comparing numbers and proportions.
Common Types: Line charts, Scatter charts, Bar charts, Gantt charts, Pie charts, and Pictograms.
X-axis is usually the independent variable, Y-axis the dependent value

Schematics

Visual representations of systems or procedures.
Include diagrams/flowcharts visually demonstrating systems structure or procedures.

Tables

Orderly data display. Tables are not charts.

Images

Add interest and visual detail. Should be relevant but use caution in copyright.

Alterations of Photographs

Ensure photographs relate to the text.
Appropriately document any alterations (e.g., contrast, brightness or hue changes)

Typographies

Typography involves arranging letters and text
Font selection should cater to readability and comprehension.

Fonts (Consideration)

Serif vs. Sans Serif: Choosing the right font for readability, heading vs body copy
Font type choice: Avoid artistic fonts in technical writing
Font size: Ensure readability

Typographies: Emphasis

Strategies: Use boldface.

Typographies: Special Formatting

Mathematical terms (e.g., corollary, definition, theorem, rule, proposition)
Presenting mathematical terms in large and small caps if necessary.

General Guidelines & Considerations

Include visuals only when appropriate.
Visuals should assist with understanding. They should be uncluttered and easy to understand.
Visuals should meet readers' format expectations. Try to avoid copying without referencing.
Referencing visuals in the text before they appear.
Visuals should have clearly labeled titles.
Using caption for tables on top and figure captions below.
When visuals contain copyrighted info, document accordingly.
Ensure that colors in visuals are adaptable to grayscale and consider color blindness.

Don't: Axis Truncation

Significant differences in data should not be hidden by truncated axis.
Similar colors can result in confusion.
Ensure titles include necessary information, e.g. date range.
Units should be clearly indicated

Don't: 3-D Distortion

Avoid if not necessary

Activity 4 (Readability Enhancement)

Download the provided word document
Enhance readability using visuals
Upload enhanced document

Team Writing

Collaborative document production
Team members contribute to decisions about function and content
Define roles and responsibilities
Establish a plan for collaboration
Produce multiple drafts for editing and revision
Review collaboratively and deliver required outcome

Form Teams

Random/self-determined grouping
Proximity
Expertise-based
Based on management assignment

Lead Writer Role

Collaborating with team members
Creating clear transitions
Ensuring unity of voice, tone and style
Editing and proofreading final document

Tools for Team Collaboration

Word processing tools (comment, revision, highlighting)
Messaging apps (instant messaging, emails)
Video conferencing (e.g., Zoom, Microsoft Teams)
Shared document workspaces (e.g., Google Docs)

Revision Strategies

Start with positive feedback
Prioritize the major issues (organization, structure, logic, and visuals design)
Focus on the document, not the writer
Address issues of clarity and relevance
Address any omissions

Cultural and Gender Issues in Team Writing

Cultural differences affect communication (e.g., asserting opinions, saying "no", requesting clarification when confused)
Gender differences affect team dynamics (e.g. valuing cooperation, consensus, and empathy)

Team Writing Challenges

Requires more time
Can lead to disjointed documents or uneven workloads
Can reduce motivation
Can lead to interpersonal conflicts

Presenting Technical Information

Speaking Situations in technical presentations, advantages of presentations, process of a presentation (preparation phase, slides production phase, performance phase). Different types of speaking situations (manuscript, extemporaneous, impromptu).

Manuscript Speaking

Fully prepared and scripted presentations
Useful for complex situations, translations, and legal statements
Best avoided in business contexts when lengthy.
Should have emphasis using added gestures and inflection

Extemporaneous Speaking

Planned but conversational
Ideal for technical presentations
Use notes/slides but avoid reading from text

Impromptu Speaking

Spontaneous, little or no time to prepare
Useful in informal situations (e.g., staff meetings)
Anticipate possible questions
Buy time, restate request, or introduce the topic.

Advantages of Presentations

Dialogue between presenter and audience
Audience participation (comments, questions)
Opportunity for audience/presenter discussion before and after presentation

Phases of a Presentation

Preparation phase
Slides production phase
Performance phase

Presentation Time Management

Honor time constraints
Allow time for questions

Visual Aids Considerations

Relevance: Visuals should support and exemplify the text.
Clarity: Visuals should not use excessive animations or sounds
Size: Ensure large enough to read in a physical/online setting
Appropriateness for medium and situation

Recommendations on CV Writing

Employ clear fonts
Use bulleted points and headings
Be concise and use exact point-based info
Have another individual proofread

CV Sections

Contact details
Introduction (Objective)
Education history
Work history
References

Poor vs. Proposed Email Examples (email content analysis).

Brief, concise emails, with context to topic and tone appropriate to situation
Contact info and appropriate salutations

Studying That Suits You

Use AI to generate personalized quizzes and flashcards to suit your learning preferences.

Description

This quiz tests your knowledge on best practices in technical writing and documentation. It covers the use of visuals, procurement documents, and effective communication strategies. Enhance your skills in creating reader-centered and accurate documents.