Technical Writing II

• Acknowledgement:– This lecture notes are based on many on-line

documents.– I would like to thank these authors who make

the documents available to the public.– Special thanks are dedicated to Prof. Kevin L.

Moore of Johns Hopkins University.

Engineering is Documentation

• Written Reports– Proposals– Interim reports– Status reports– Final report

• Presentations – Design Proposal – Critical design review (CDR)– Final design review (FDR)

Basic Elements of Effective Writing

• 1. Know your purpose• 2. Know your audience• 3. Choose and organize content around

your purpose and audience• 4. Write precisely and clearly• 5. Design your pages well• 6. Think visually• 7. Write ethically

Know Your Purpose

• Why is this communication occurring?– Proposals?– Interim reports for further funding?– Reporting results for final signoff?– Justification to management?

Know Your Audience

• Categories of audiences:

• What is the technical level of the target audience?

• What is their interest in this presentation?

• Many times multiple versions of documentation my be prepared for different audiences

1. Laymen 2. Executives 3. Experts 4. Technicians

5. Combined Audiences

Organize the Content Around the Purpose and the Audience

• General overviews to specific details

• Specific details to general concepts

• Describing events chronologically

Write Precisely and Clearly

• Use short paragraphs with a single idea

• Short direct sentences

• Active voice and action verbs that are clear on what is said and what is being done.

• Opinions and viewpoints should be clearly identified as such

• Don’t use Doublespeak. Say precisely what you mean.

Design Your Pages Well

• Use Judicious headings to organize the structure

• Break long sections into subsections to keep the readers interest

• Use appropriate fonts

• Use white space to guide the reader to the important areas

Think Visually

• Pictures

• Sketches and drawings

• Tables

• Simple flow graphs

• Use color where appropriate

• Keep visuals simple, don’t make them cluttered

Write Ethically

• Present facts accurately

• Report unfavorable results along with the favorable

• Present the limitations of the design

• Give full credit to others (references)

• Engineering is not marketing…

Project Report

• The purpose is to communicate to the client what the design team did, and why they did it.

• Decisions should be explained and justified

• Results should be summarized and made clearly

Project Report(Structured Design)

• Determine the purpose of and audience for the report

• Construct a rough outline of the structure

• Review the outline with the team and with managers

• Construct a topic sentence outline and review it with the team

Project Report(Structured Design)

• Distribute individual writing assignments

• Write and assemble an initial draft

• Solicit reviews of the initial draft

• Revise and rewrite the initial draft (editor)

• Prepare a final version of the report and present it to the client

Purpose and Audience

• Is this a technical report?

• Is this a report to educate marketing?

• Is this a report to management to justify our continued employment?

• Who are we talking to and why do we want to talk to them?

The Rough Outline

• Abstract• Executive summary• Introduction and overview• Analysis of the problem, including relevant prior work• Design alternatives considered• Evaluation of design alternatives and basis for design

selection• Results of alternatives analysis• Design selection• Supporting materials (references, drawings,

specifications, calculations, etc)

Topic Sentence Outline

• Each entry in a TSO corresponds to a single paragraph in the report.

• This is where the logic of the argument is laid out.

• Helps eliminate duplication

• Identifies cross references

• Enables fair distribution of writing load

Grandmother Principle?

Grandmother Principle

• The first page of every chapter,

• the first paragraph of every section, and

• the first sentence of every paragraph

• Should be comprehensible to your grandmother

Topic Sentence Outline

The First Draft

• The raw material of the first draft often is written in the each of the voices and writing styles of the individual team members. An editor is essential.

• The tasks of the editor include continuity of flow, consistency of style and content, and accuracy of material.

• The editor should have the authority to rework material into a single voice.

Final Report

• Clearly organized• Easy to read and understand• Graphics and figures are clear and easily

interpreted• Process and argument are clearly defined

and defended• Should be complete (includes all

documentation to let it stand alone as a complete description of the design

Guideline for Final Report • Should be detailed enough to let the readers understand your

project goal, your achievement, and technical details (such as procedures, material and methods, etc.).

• Abstract• Table of Contents• List of Figures• List of Tables• Introduction (project objectives, background information, summary of

achievements, etc. )• Technical Details (Analysis of the problem, design alternatives

considered, evaluation of design alternatives, design selection, etc)• Lessons Learned (problems encountered, possible solution or

suggestions, etc)• Conclusion (summary of your achievements)• Bill of Material (list the components you ordered, including model#,

price, source, contact, website or Tel. No. )

• References (list the papers, patents, or websites you have referred) •

• Appendices (include program source code, PCB or mechanical drawings, reference manual of the components you used in the design)