WRITING TECHNICAL DOCUMENTATION American River College Shannon Mendez
OBJECTIVES Describe what technical documentation is. Recite some types of technical documentation. Describe technical documentation elements. Describe a technical reference sheet.
OVERVIEW: WHAT IS TECHNICALDOCUMENTATION? Technical documentation informs and instructs readers about science and technology. It can include detailed information about scientific theories, as well as instructions for using software and hardware.
SOME TYPES OF TECHNICALDOCUMENTS User’s Guides Programmer’s Guides Training Materials Online Help Systems Reference Sheets/Getting Started Guides
ACCURATE• Document Accuracy: Choose the proper document type for the purpose. For example: Getting Started Guide, Reference Manual, Tutorial, Online Help System, Website.• Stylistic Accuracy: Purposeful writing with legal precision: Paragraph structure, sentence structure, grammar, tone, and so on.• Technical Accuracy: Must properly represent the subject.
CLEAR• Well-organized, effective design: Sections, graphs and tables, titles, frequent headings, icons.• Simple, direct language: Simple sentences, active voice, plain language.• Invisible writer: Reveal nothing about yourself in the writing.
CONCISE• Reader-based: What does the reader need to know?• Careful editing: Prune all words that are not needed.
COHERENT• Consistency: Fonts, organization, words.• Paragraph Development: Topic sentences, supporting sentences. Repeat nothing.• Transitions: Topic and concluding sentences, Beginning words within paragraphs.
APPROPRIATE• Do not deviate from the document’s purpose• Write to the level of the audience
WRITING TO THE AUDIENCE Audience type and expertise levels Experts, managers, technicians, layperson/users Use of document Three main purposes: to acquire information, to help make decisions, to learn how to do something
WRITING A TECHNICALREFERENCE SHEET Used as a reminder. Used as a “quick tip” sheet of the most common or most important tasks. Can be thought of as “the top layer of the onion,” a job aid
REFERENCE SHEET EXAMPLES (click the pictures to view the documents)
REVIEW & QUESTIONS Can you answer the following questions?: Describe what technical documentation is. Recite some types of technical documentation. Describe technical documentation elements. Describe a technical reference sheet.