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. Laymen2. Executives3. Experts4. 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)