Principles of Technical Writing

Training Manual
Course Module 1

Your Key to Technical Writing Success

Copyright and Disclaimer

This book is published and printed at TechnoPoint. All rights reserved. No part of this book may be reprinted or reproduced or utilized in any form or by any electronic, mechanical or other means now known or here after invented including photocopying and recording, or in any information storage

Principles Of Technical Writing

Table Of Contents
Preface ............................................................................................... 1 Over view of the chapters .................................................................. 1
Introduction to Technical Writing .................................................................................................... Software Development Life Cycle .................................................................................................. Documentation Process ................................................................................................................. Communication Products ............................................................................................................... 1 1 1 1

Introduction to Technical Writing ........................................................ 1
Definition .............................................................................................................2

Skills Technical Writer should acquire ............................................... 2
Technical Communication .................................................................................3 Project Management ...........................................................................................3
Teaching ......................................................................................................................................... 3 Research ........................................................................................................................................ 3 Software ......................................................................................................................................... 3 Technical ........................................................................................................................................ 3

Software Development Life Cycle ..................................................................... 4 Introduction ......................................................................................................... 4
Software Requirement Analysis ..................................................................................................... 4 Analysis of Software Design ........................................................................................................... 4 Software Coding ............................................................................................................................. 4 Software Integration ....................................................................................................................... 4 Software Testing............................................................................................................................. 4 Software Release ........................................................................................................................... 4 Software Maintenance .................................................................................................................... 4

Software development models .......................................................................... 5
Linear Sequential model. ................................................................................................................ 5 Introduction..................................................................................................................................... 6 STUDY, RESEARCH AND INTERVIEW TO GET INFORMATION. .............................................. 6

Documentation Planning.................................................................................... 6
Purpose and Structure .................................................................................................................... 7 Assumptions about audience training: ............................................................................................ 7 Planning a Document Content ........................................................................................................ 7

Communication Products................................................................... 9
User Guide ..................................................................................................................................... 9 GENERAL FORMAT FOR DEVELOPING USER GUIDE .............................................................. 9

Operation manual .............................................................................................10
GENERAL FORMAT FOR OPERATION MANUAL .................................................................... 10

Reference Manual .............................................................................................10
GENERAL FORMAT FOR REFERENCE MANUAL .................................................................... 10

Release notes ....................................................................................................11 Installation Guide ..............................................................................................11
GENERAL FORMAT FOR INSTALLATION GUIDE...................................................................... 11 INSTALLATION PROCEDURE .................................................................................................... 11

Proposals........................................................................................................... 12
Proposal Writing Situation ............................................................................................................ 12 Your Audience .............................................................................................................................. 12 Problem ........................................................................................................................................ 12

i

Principles Of Technical Writing

Solution ......................................................................................................................................... 12 Costs ............................................................................................................................................ 12 Capability...................................................................................................................................... 12 Structure for Proposals................................................................................................................. 12 Introduction ................................................................................................................................... 13 Problem ........................................................................................................................................ 13 When Your Readers Define The Problem .................................................................................... 13 When Your Readers Provide A General Statement Of The Problem.......................................... 13 When You Must Define The Problem Yourself ............................................................................. 13 Objectives..................................................................................................................................... 14 Product ......................................................................................................................................... 14 Method.......................................................................................................................................... 14 Qualifications ................................................................................................................................ 14 Management................................................................................................................................. 15 Costs ............................................................................................................................................ 15

Business Plan ...................................................................................................15
INTRODUCTION .......................................................................................................................... 15

Structure of Business plan ..............................................................................15
Proposal Content .......................................................................................................................... 15 Introduction................................................................................................................................... 15 Market Analysis ............................................................................................................................ 15 Proposed Business ....................................................................................................................... 16 Products Or Services.................................................................................................................... 16 Business Site................................................................................................................................ 16 Schedule....................................................................................................................................... 16 Qualifications ................................................................................................................................ 16 Budget .......................................................................................................................................... 16 Conclusion .................................................................................................................................... 16

Booklets............................................................................................................. 17 Brochure ............................................................................................................17 Tutorial / Training Guide .................................................................................. 17 Reference manuals ...........................................................................................17
User Reference Manuals .............................................................................................................. 18

Reports ..............................................................................................................18
Scientific Research Reports .......................................................................................................... 18 Business Research Reports ......................................................................................................... 19

Instructional Design ......................................................................... 19
Instructional System: .................................................................................................................... 19 User Interface Design ................................................................................................................... 19

Technical Reports............................................................................................. 20 Contents of a Document .................................................................................. 20 Illustrations ........................................................................................................21
Cross-reference ............................................................................................................................ 21 Endnotes ...................................................................................................................................... 22 Footnotes...................................................................................................................................... 22

Audience Analysis ............................................................................................ 22
Conduct an an audience analysis................................................................................................. 23 Identifying Audience Characteristics ............................................................................................ 23 Assessing Audience Objectives and Needs ................................................................................. 23 Preparing the content ................................................................................................................... 24 While writing ................................................................................................................................. 24

ii

Principles Of Technical Writing

Oral Presentations ............................................................................................24
How Visual Aids Help ................................................................................................................... 25

iii

Principles Of Technical Writing

Preface
This reference guide gives information about the different aspects involved inTechnical Writing. This reference manual deals with the introduction to Technical writing, skills required to be a Technical writer, understanding of Software Development Life Cycle (SDLC), Documentation Process, ISO, Capability Maturity Model (CMM), and general format for different technical manuals like user’s guide and online help.

Over view of the chapters
Introduction to Technical Writing
This chapter provides information on basics of Technical writing and skills a Technical Writer should acquire.

Software Development Life Cycle
This chapter provides information on the Software development life cycle anddifferent development models.

Documentation Process
This chapter provides information on the process adopted for developing userdocumentation.

Communication Products
This chapter provides information on the different communication products andtheir general format.

Introduction to Technical Writing
Organizations that develop Information Technology solutions like software with no support documents to ease the use were seen in bad light as the end users found it extremely difficult or rather impossible to work with them.The complexity involved in the usage of different products and software solutions has created a need to provide information to understand these Products or software’s better. The end users of these products and solutions need to have enough information to utilize the features offered. This is where a Technical writer contributes. A Technical Writer develops communication products to help users understand the product or software solution better.

1

Principles Of Technical Writing

Definition
Technical writing is a specialized field that requires various skills - the ability to write clearly and concisely, the ability to organize content, a good understanding of technical products and processes, and knowledge of numerous documentation productivity tools.2 A Technical writer should: Understand the type of technical report you are writing 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. Keep information specific rather than general Match content to your readers' knowledge and needs Plan the sections and subsections you need Write your headings using strong verbs and specific nouns Write in plain English Use active verbs rather than passive verbs Maintain your average sentence between 15 to 20 words Restructure wordy phrases Write using simple words rather than complex ones Avoid jargon Keep technical terms to a minimum Use diagrams, flowcharts and graphs Design a good layout to draw attention to key information Test your document with the intended readers

Skills Technical Writer should acquire
Technical Writers must have a flair for writing and capability to understand the technology involved in developing the product or software solution. Technical Writers must acquire the following skills: • • • • • Communication Project Management Teaching Research Software

2

Principles Of Technical Writing

Technical Communication
Technical Writer should adopt proper usage of language. Develop Interpersonal skills like empathy, negotiation, persuasion, and ability to socialize. Technical Writers must also understand the nuances of interviewing because Technical writers should interview subject matter experts (SME) and gather information from them. Subject matter experts are domain experts who develop products and solutions. echnical writers must empathize with their readers, conduct an audience analysis in order to determine their readers, be aware of their phantom readers.

Project Management
Technical Writers should learn to manage documentation projects, this requires understanding project management. Project management involves organization and time management. Technical Writers should organize all the aspects of document production, keep track of project components and take decisions. Time management is integral to Technical Writing, especially when dealing with multiple projects.

Teaching
Communication products developed by Technical Writers should facilitate learning.

Research
Technical writers must study and analyze relevant information from different sources. Those, endowed with natural curiosity have an advantage. One’s learning process will help shape their documentation.

Software
Technical Writers should be well versed with the documentation software’s like Adobe Framemaker, Adobe Photoshop, and Microsoft word. Knowledge of one documentation software makes it easier to learn the other. Technical Writers with knowledge of RoboHelp can create versatile online help manuals.

Technical
Knowledge of one or more programming languages makes the Technical Writer useful for employees. Some companies expect Technical Writers to maintain their company websites. Technical Writers with knowledge of HTML or XML will be able to maintain websites and there by be an asset to the employer.

3

Principles Of Technical Writing

Software Development Life Cycle Introduction
In order to understand the documentation process prevalent in organizations, it is necessary to understand how the software development life cycle works. This is necessary as documentation process orients itself with the software development life cycle.

Software Requirement Analysis
The business development team collects information from the customer. An exhaustive requirement analysis is done and documented in Software Requirement Specifications.

Analysis of Software Design
Based on the Software Requirement Specifications an in-depth analysis is conducted to design the software. The software is broken down to manageable components called modules. The different modules are designed in detail. The software design is generally modular. Modular development makes the software development manageable.

Software Coding
The different software modules are developed based on the design document.

Software Integration
The software modules are integrated.

Software Testing
The integrated software is tested for conformance with the requirements and the design.The software is subjected to alpha testing. After the software has passed the alpha testing. The software is subjected to Beta testing .. Hence the names Alpha versions and beta versions. After the software is installed at the clients premises and tested from the clients location

Software Release
The final version of the software is shipped to the customer.

Software Maintenance
The software is maintained at the customer’s premises.

4

Principles Of Technical Writing

Requirement

Analysis of

Coding

Integration

Testing

Documentation

Release

Maintenance
Figure 1: Software Development Life Cycle

Software development models
Linear Sequential model.
Software development life cycle in its simplest form called the linear sequential model consists of • • • • Analysis – Analysis of Requirements Design – Design of solutions Coding – Development of solution Testing – Test the solution developed for flaws before

5

Principles Of Technical Writing • • Analysis Design Coding Testing Documentation Process

Analysis

Design

Coding

Testing

Figure 2: Linear Sequential Model

Introduction
The process involved in developing a technical manual usually involves team effort. In most situations, a Technical Writer or Technical Communicator is only given one portion of the whole project. Other parts go to the Graphical designer, Editor and such. The “whole picture” of the project is usually only seen by the Project Manager. Whether the whole job or part of the project has been assigned to the technical communicator, you need to know the process involved in creating the manual. • • • • • • • Steps involved in documentation Study, research and interview to get information. Outline and organize the technical manual. Draw or get graphics from the team. Transform technical material into common language. Edit written material. Print and bind material.

STUDY, RESEARCH AND INTERVIEW TO GET INFORMATION.
The technical writer collects the information from the subject matter experts.

Documentation Planning
Analyse the Audience Identifying audience characteristics ,Knowledge and experience level ,education background Accessing Audience a) Objectives and Needs: Is the activity the audience wants to be able to perform after reading the document. b) Write for one audience group at a time and indicate which group you are addressing.

6

Principles Of Technical Writing

Purpose and Structure
Identifying a document purpose and structure by asking questions such as: 1.Dose the audience need long term or short term knowledge? 2.Will the audience need peripheral as well as essential information? 3.How much depth of information does the audience require?

Assumptions about audience training:
Use the following questions to characterize an audience training: 1. Is the audience familiar with the product, service and software 2. Is the audience familiar with the task, situation on problems? 3. Can the document assume the audience has a group of basic concepts of background information?

Planning a Document Content
After analyzing the audience and choosing the appropriate medium for the document, plan its content, the documents structure – the information order and its level of detail. Document Planning involves: • • • • • • • Collecting information about the subject Selecting an organizational method Preparing an outline Collecting information about the subject Analyse written source material Interviewing sources Conducting a hands-on evaluation

7

Principles Of Technical Writing

Study Existing Information - SRS

Interview SMEs

Review Process - Peer Review - Documentation Manager Review - Functional Mangers’ Review or Engineering Department Review - Customer Review Draft Table of contents (TOC)

Write based on the approved TOC

Complete first level document (25%)

Complete Second level document (75%)

Complete final document (100%)

Release
Figure 3: Documentation Development Life Cycle

8

Principles Of Technical Writing

Communication Products
The communication products Technical writers develop are: • • • • • • • • • • User guide Online help Operation manual Reference manual Training manual Release notes Installation guide Trouble shooting guide Brochures and Booklets Technical Reports

User Guide
User guides provide information required to work with different products and different solutions.

GENERAL FORMAT FOR DEVELOPING USER GUIDE
Name of the solution or software, version details, organization logo. Need for documentation, declarations, commercial or business interface information like Copyright, registered trademarks, service marks, license agreement details, license owner details, Partnership agreements, and disclaimers. Acknowledgements Brand Uniqueness, Safety features (in case of Hardware products) 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. Contents Introduction System Requirements New Features Audience Getting started or quick guide Information to experienced users Alternate help features Technical support Security Contents based on user interface or task General reference Supporting technical information Source Trouble shooting Glossary Index

9

Principles Of Technical Writing

Operation manual
Operation manual offers the user, necessary information required to operate systems.Operation Manual is a supplement for Products of the Hardware origin.

GENERAL FORMAT FOR OPERATION MANUAL 1.
2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. Heading with organizations details Disclaimer, copyright information, suitability criteria, limitation of warranty License agreement Contents Introduction Installation details Configuration Setup for fitness testing Background preparation in case of Bio-engineering systems Customization Usage Reporting formats Deliverable format Troubleshooting Communications Compatibility Miscellaneous Appendix Index

Reference Manual
Reference manuals offer quick information about the procedures to be followed, in order to complete the user’s tasks.

GENERAL FORMAT FOR REFERENCE MANUAL
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. Preface or Front matter Order Number Overview Standards Conformance Compatibility Contents Introduction Basic features Complexities or Uniqueness Commands or Procedures Variables Features Control Using past references

10

Principles Of Technical Writing 15. 16. 17. 18. 19. 20. 21. 22. 23. Installing the software Reporting bugs Discussion on obsolete features Index Index of commands Index of reserved words Parameter and variable index Function index Concept index

Release notes
Release notes contain release information, version enhancements, known issues, and bug fix. Release notes suggest workarounds possible. GENERAL FORMAT FOR RELEASE NOTES • • • • • Installation details, software uninstall details Known issues Fixes Workarounds Caveats

Installation Guide
Offers step by step procedure to install products.

GENERAL FORMAT FOR INSTALLATION GUIDE
1. 2. 3. 4. Product logo, Organization notes, general communication Contents Introduction Documentation Convention, How to use this document? Recommended Configuration, System compatibility, Installation prerequisites

INSTALLATION PROCEDURE
1. 2. 3. 4. 5. 6. 7. Steps to get you started Where to find supporting information In case of software, Memory compatibility Customizing installation System Upgrades If failed Trouble shooting Support Actions

11

Principles Of Technical Writing 8. 9. 10. 11. Additional Support Additional options Index Colophon

Proposals
When you write a proposal, you make an offer and try to persuade your readers to accept it.

Proposal Writing Situation
Your readers may be peers, seniors, competitors, government departments, and

venture capitalists. Your Audience
Your audience is investors, and decision-makers who make cautious investments. Readers will question you on purchases and projects

Problem
Readers will want to know why you are making your proposal and why they should be interested in it. What problem, need or goal your proposal address - and why is it important to them?

Solution
Your readers will want to know exactly what you propose to make or do and how it relates to the problem you describe.

Costs
Your readers will want to know what it will cost to implement your proposal and whether the cost will be worth it- to them.

Capability
If your readers pay or authorize you to perform the work, how will they know whether they can depend you to deliver what you promise?

Structure for Proposals
Conventional superstructure presented here must be consumed as a general plan. You must use your imagination and creativity to adapt it to particular situations. Proposal can contain the following headings

12

Principles Of Technical Writing • • • • • • • • • Introduction Problem Objectives Product Method Resource Qualification Management Costs

Introduction
Tell your readers what you are writing. Announce what you will be proposing. Postpone the full description of what you are proposing to a later stage. Keep your introductions brief.

Problem
Once you’ve announced what you’re proposing. You must persuade your readers that it will address some problem that is significant to them. Although you can persuade your reader that your proposed project will achieve its objectives and that its costs are reasonable, you cannot hope to win approval unless you show that it is worth doing from your readers’ point of view. You must not only identify a problem but make it interesting to your readers. Not only define a goal but make its achievement seem worthwhile to your readers. To do this requires both creativity and research. Furthermore, just how you describe the problem will depend on the situation. There are three different situations you can encounter on the job.

When Your Readers Define The Problem
The readers might issue a RFP that explains in complete detail, some technical problem they would like your firm to solve. In such situations your primary objective is to show your readers that you thoroughly understand what they want.

When Your Readers Provide A General Statement Of The Problem
You have to derive an RFP from the general statement.

When You Must Define The Problem Yourself
In this scenario, you will not have the aid of an explicit statement from your readers to help you formulate the problem. Some of the questions you need to keep in mind are How you can make your proposed project important to your reader?What goals or responsibilities do your readers have that your proposal will help them achieve?What concerns do they typically

13

Principles Of Technical Writing express that your proposal could help them address? A good place to think is from efficiency and profit.

Objectives
In conventional superstructure for proposals, writers usually state the objectives of their proposed solution after describing the problem they are proposing. Your statement of objectives plays a crucial role in the logical development of your proposal: it links your proposal to your problem by telling how the action will solve the problem.

Product
When you describe the product of your proposed project, you describe your plan for achieving the objectives you have listed. To describe your product persuasively, you need to do three things • • • • Be sure to let your readers know how you will achieve each of your objectives. Provide enough details to satisfy your readers that you have planned your product carefully and thoughtfully. Explain the desirability of the product.

A NOTE ABOUT THE RELATIONSHIPS AMONG PROBLEM, OBJECTIVES, AND PRODUCT The three elements are related to one another. You can increase the likelihood of success by ensuring that your objectives grow directly out of your statement of the problem, and that your product will address those objectives directly.

Method
The readers of proposals need to be assured that you can, in fact, produce the results that you promise. Especially in situations where you are proposing to do something that takes special expertise. To assure themselves the readers will look for.Your method or plan of action for producing the result. The facilities, equipment, and other resources you plan to use. 1. 2. 3. 4. Your schedule. Your Qualification. Your Plan for managing the project. Resources (Include resources only if you need special resources.)

Qualifications
When proposal readers are thinking about investing in a project, they want to be sure that the proposers have the experience and capabilities to carry it out successfully.

14

Principles Of Technical Writing

Management
When you propose a project a project that will involve more that about four people, you can make your proposal more persuasive by describing the management structure of the group.In larger projects provide the organizational charts.

Costs
As emphasized throughout this write-up, when you propose something, you are asking your readers to invest resources, usually money and time. Naturally, then, you need to tell them how much your proposed project will cost. Include a budget statement.

Business Plan
INTRODUCTION
One of the main arsenals Entrepreneurs process is a sound business plan that can catch the attention of a discerning venture capitalist. Business plan offers the necessary information to the investors.

Structure of Business plan
Proposal Content
For details on Proposal content, refer to the proposals section under the communications products chapter.

Introduction
Briefly explain that you are responding to the Request for Proposal(RFP). Tell how much money you want to borrow. Forecast the contents of the rest of your proposal.Introduction should not exceed one page.

Market Analysis
Provide persuasive evidence that market exists for the business you are proposing. Who will be your end users? What are the important characteristics of these people from the point of view of your proposed business? Also discuss any compeFundamentals of Technical Writing tition that exists and explain how you can compete effectively against it. If you cannot talk about any competition then talk about a similar business that has been tried in your community but has failed. This chapter has to be as long as is required to persuade your readers that a substantial market exists for the business you are proposing.

15

Principles Of Technical Writing

Proposed Business
This chapter should be the longest in your proposal. Cover the products, business location, marketing plan and staffing.

Products Or Services
Tell specifically and in detail what your business will sell. Relate these products or services directly to your market analysis.

Business Site
Discuss in detail the physical layout of your business with explanations as to how this would make your business more appealing. • • • • • Marketing Plan Talk about your plan to attract customers Staffing and Management Indicate how many people you will hire. Describe the business management structure, keeping the structure as simple as possible.

Schedule
Provide a prose overview and a Gnat Chart of the major events in the development of your business. Begin with approval of your proposal and continue to the point where your business is fully established and you can start making payments on your loan.

Qualifications
Explain your qualifications to run the business you propose.

Budget
Explain the projected expenses and income from your business. Discuss initial expenses, operating expenses, and projected income.

Conclusion
Briefly summarize your proposal and bring to an appropriate end. Conclusion should not exceed one page.

16

Principles Of Technical Writing

Booklets:
Booklets are generally more extensive than brochures, they convey introductory or overview rather than marketing information about a topic. A booklet often targets a specific group.

Brochure
A brochure typically serves as a marketing or promotional tool. In addition to selling product or services. Brochures can be used to offer brief description overview. Brochures are usually brief rarely more than 16 pages regardless of the page size. To attract readers, a brochure often uses photographs, illustrations clear headings and colour. Because a brochure is generally read quickly use short sentences and paragraphs and insert frequent headings to mark major topic divisions.

Tutorial / Training Guide
A tutorial uses explanations, repetitions, hands on, practice, exploratory learning and other motivating methods to help the reader attain a desired skill level. Typically, tutorial / training guides are produced either as stand alone documents or as part of classroom instruction. A stand above tutorial helps the reader learn without an instructor. In a tutorial a sequence of procedure is important and should be designed to aid learning, simple skills lead to complex skills and general principles to particular applications.

Reference manuals
Reference manuals provide encyclopedic information about a product, including complete technical details about its operation. They are not task-oriented and are organized alphabetically, numerically or by product features. A Reference manual shows how a system is designed and operates. For example, the reference manual for a multiple-line telephone system may contain writing schematics and switch-setting tables of interest to technical but not to telephone users. Many reference manuals are multipurpose and serve the needs of installation, operations and maintenance personnel. However, a complicated system may require a separate reference manual for each task or component.

17

Principles Of Technical Writing

User Reference Manuals
User Reference manual is a compromise between a user guide and a reference manual. Choose it when resources or schedule dictate that a product have only one manual. While most user guides address only primary tasks, a user reference manual describes everything a user can do with a system. User reference manuals generally includes both procedures and concepts as well as a reference sections, effective headings, cross references and a good index help readers who often have varied technical background and experience, find specific information. User reference manual should be task oriented, because it must be complete information source.

Reports
Reports which answer a question or offer a solution to a problem, generally support four basic activities. 1.Scientific Research Reports 2.Business Research Reports 3.Progress or Status 4.Proposals Reports generally range from 5 to 20 pages. Those written for business or internal audiences are generally shorter and less formal than those written for scientific or external audience.

Scientific Research Reports
Scientific research reports are the results of formal scientific studies. Since the audiences for such reports are experts use technical terms and concepts without background explanation. 1.Title and author attributes: describes the content using appropriate keywords. 2.Abstract: summarizes the objective, methods, results and conclusions. 3.Introduction: presents the research objective and hypothesis. 4.Literature review: overview of the current state of research and the theoretical foundation for the study. 5.Procedure: describes the subject method and materials used in the study. 6.Results: summarize the data collected from the study using graphs, charts, and tables with accompanying narrative explanation, present this data objectively and without interpretation.

18

Principles Of Technical Writing 7.Conclusion: Discuss and interpret the results. 8. Appendix: provides additional information such as data, they may be inappropriate within the text.

Business Research Reports
Business research reports provide data and answer questions to support making an important decision or taking specific action. The form of business research reports is similar to scientific research reports. Tittle and author attributes- Precisely describe the content using appropriate key words that can assist in searching for the published report. Executive Summary - Summarizes the center report in one page or less emphasizing the recommendation and conclusions. Introduction- Explains the reports purpose and the question or problem it addresses. Body- Provides a literature review, study results, and /or the authors analysis of the problem or situation. Recommendation and Conclusion- Propose a detailed course of action. Appendix- (if necessary) provides additional information, such as data that may be inappropriate within the text.

Instructional Design
Instructional design is the systematic development of instructional specifications using learning and instructional theory to ensure the quality of instruction. It is the entire process of analysis of learning needs and goals and the development of a delivery system to meet those needs. It includes development of instructional materials and activities; tryout and evaluation of all instruction and learner activities. Instructional design is the science of creating detailed specifications for the development, implementation, evaluation and maintenance of situation that facilitate the learning of both large and small units of subject matter at all levels of complexity.

Instructional System:
Is an arrangement of resources and procedure tom promote learning instructional design is the systematic process of developing instructional systems and instructional development is the process of implementing the system or plan.

User Interface Design
Many technical innovations rely upon user interface design to evaluate their technical complexity to a usable product technology above May not in user acceptance and subsequent

19

Principles Of Technical Writing marketability. While product engineers focus on the technology, usability specialists focus on the user interface for greatest efficiency and cost effectiveness. This working relationship should be maintained from the start of a project to its rollout. Optimized user interface design requires a systematic approach to the design process. The importance of good user interface design can be the difference between product acceptance and rejection in the market place. If end-users feel it is not easy to team, not easy to use or cumbersome; an otherwise excellent product could fail. Good user interface design can make a product easy to understand and use, which results in greater user acceptance.

Technical Reports
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. Understand the type of technical report you are writing. Write down your specific aim plan the section and subsection you need Avoid starting with background, introduction and methodology Writing your headings using strong verbs and specific nonus Match content to your leaders knowledge and needs Keep the information specific rather than general Write in plain English Use active verbs rather than passive verbs Keep your average sentences between 10 to 20 words Edit wordy phrases Use simple words rather than complex ones Avoid Jargon. Keep technical terms to a minimum. Use examples and illustrations. Use diagrams, flowcharts and graphs. Use good layout to draw attention to key information.

Contents of a Document
1.Clearly states the purpose, providing a explicit justification for the document 2.Explicitly defines the scope of the reader. 3.Is factually correct. 4.Support the purpose thoroughly and concisely. 5.Substantiates claims and when appropriate addresses alternative claims. 6.Shows that the writer understands the topic under discussion. 7.User language to correct the pieces of the argument or document.

20

Principles Of Technical Writing 8.User non-textual elements (graphics, charts, equations) that are necessary for clarity are Illustrations.

Illustrations
Illustrations can be used in a variety of documentation types from job training material to proposals, brochures and pamphlets. Illustrations can 1.Add information 2.Help explain content 3.Visually confirm information in text 4.Motivate readers and maker reading more interesting 5.Provide visual relief for a page heavy with text and sometimes replaces text Using illustrations will help readers 1.Perform procedures 2.Visualize mechanisms and processes 3.And remember what they have read. It is helpful when the readers have limited reading skills- may not have on-the-job time to read or Speak a language other than English

Cross-reference
Use cross reference to provide guides to related information. There are two types of Crossreferences, See and See also In the See cross-reference all the information related to a term is included within another term. If a See references is used, try to provide atleast two locations. The See also cross-reference directs the reader to an entry that contains additional related information. See also cross-reference often point from the general to the specific, as well as among topics with a close association. In Cross-referencing, avoid 1.Creating a faulty logical relationship between entries. 2.Blind See references pointing to non-existing headings. 3.Circular searches e.g., Insert gases 150, 177 See also Neon, See Insert gases.

21

Principles Of Technical Writing

Endnotes
Endnotes are similar to Footnotes, except endnotes are grouped together at the end of the entire work or at the end of individual sections, rather than at the bottom of the page. Place endnotes numbers at the end of a sentence. So that they do not interrupt the text. Use a small superscripted number placed after any punctuation to refer to a specific endnote. Endnotes numbering begin at one (1) and continue sequentially within chapters. The word only requires special care, as it is frequently misplaced. Note the different meanings given to the following sentences by placing only in different positions.

Footnotes
Footnotes are the traditional and accepted method for citing and documenting sources in many disciplines. Place footnotes at the bottom of the page on which the reference occurs. A superscripted number follows the reference in the text. Also place the number followed by the author’s name ant the rest of the bibliographic information, as in an endnote. Footnote place references close to the text they support. This placement eliminates flipping from the text to a list of references at the end of the chapter or book. The disadvantages of footnotes: 1.Interrupt the readers by directing their attention to the note at the bottom of the page. 2.Can create typographical untidy pages. 3.Do not provide a collected resource –as endnotes do – unless they are accompanied by a bibliography.

Audience Analysis
Before writing anything, describes an audience by: 1.Conducting an audience analysis 2.Identifying audience characteristics 3.Assessing audience objectives and needs 4.Creating an audience profile

22

Principles Of Technical Writing

Conduct an an audience analysis
Conduct either a formal or an informal audience analysis. Use formal methods to gather quantifiable data, informal analysis is appropriate for small or poorly funded projects During formal analysis 1.Collect surveys and questionnaire responses. 2.Hold standard interviews 3.Conduct usability research such as foens groups, field studies or usability fests. During informal analysis gather information about the audience indirectly by: 1. Talking with marketing, development and other staff who have access to research results and customers. 2. Reading notes and reports by product trainers or maintenance personnel who have had contact with the audience. 3. Reading periodicals that relate to the product, industry or audience. 4. Talking informally with people who will read the final document.

Identifying Audience Characteristics
Before you begin writing identify and consider such important audience characteristics as1.Educational plus professional background 2.Knowledge and experience levels 3.English language ability 4.Reading context the physical and psychological conditions under which the audience reads the document.

Assessing Audience Objectives and Needs
Use audience objectives and needs to develop an approach to the document. 1.Objective- reflects the activity the audience wants to be able to perform after reading the document. 2.Needs- Indicate question the audience will have, the document should answer. 3.Defining Your Objective 4.The importance of your objective 5.A reader- centered approach to defining objectives 6. Describe the final result you desire from the reader

23

Principles Of Technical Writing

Preparing the content
1.Plan your document whenever you start to write, plan the content 2.Identify the tasks you will help your readers perform while they read. 3.Learn who your readers will be. 4.Organize hierarchically. 5.Plan your visual aids.

While writing
Begin by announcing your topic 1. How topic statements help readers (keep the reader informed in the beginning what is the topic all about) 2. Why topic statements help must at the beginning of a segment. 3. You have both the top-down processing- and the reader would have seen the final product. 4. Bottom-up processing where the user gets an overview of the product and start working on it. 5. Move from most important to least important.

Oral Presentations
Define your objective: 1. Purpose and audience (you will have to think of your audience and how you want to effect them) 2. Consider your listener’s expectations. 3. Select the form of oral delivery best suited to your purpose and audience: Scripted talk: Write out your entire talk, word to word Outlined talk: Prepare an outline Impromptu talk: one given on the spur of the moment with little or no preparation. Focus on a few main points Make the structure evident Announce, explain, review Clearly signal the transitions: listeners can have difficulty when you shift from one topic to another 8. Highlight your main points: Emphasize on each main point as you come to it. 9. Use a conversational style 10. While preparing your talk, image your listeners in the act of listening. 11. Use the word you or your in the first sentence. 12. Continue using personal pronouns throughout. 4. 5. 6. 7.

24

Principles Of Technical Writing 13. Use shorter, simpler sentences than you might use when writing 14. Pick words your listener will immediately understand.

How Visual Aids Help
1. 2. 3. 4. 5. Visual aids help you to attract and hold the attention of your audience. Visual aids will help your listeners to perceive how your talk is organized. Visuals help you to highlight the main points. Visual aids help your listeners remember what you say Visual aids help remember what you want say.

25

Principles Of Technical Writing

References:
Sharon J. Gerson and Steven M. Gerson;Technical Writing Process and Product; Third Edition,2004. Philip Rubens; Science and Technical Writing-A manual of style; 2nd edition, 2004. Paul.V. Anderson; Technical Writing - A Reader Centered Approach; 3rd edition,1995.

26

Principles Of Technical Writing

INDEX
A
Aids 25 Analysis 15

B
Booklets 17 Brochure 17 Business 19 Business Plan 15

C
Coding 4 Communication 2 Communication Products 9 Contents 20 Cross-reference 21

D
Design 19 Documentation 6

E
Endnotes 22

F
Footnotes 22

G
Guide 17

I
Illustrations 21 INSTALLATION GUIDE 11 Instructional 19 Integration 4 Interface 19

L
Linear 5

M
Maintenance 4 Management 3 manuals 17

O
Objectives 14 OPERATION MANUAL 10 Oral Presentations 24

27

Principles Of Technical Writing

P
Problem 13 Project 3 Proposals 12

R
Reference 17 reference 1 REFERENCE MANUAL 10 Release 4 RELEASE NOTES 11 Reports 18, 19

S
Software 4 Software Development Life Cycle 4 Structure 12

T
Technical 1, 3 Technical Writing 1 Technology 1 Testing 4 Training 17 Tutorial 17

U
User 19 USER GUIDE 9

V
Visual 25

28

Sign up to vote on this title
UsefulNot useful