Technical Writing and Documentation Practices

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

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.