Technical Writing Manual

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 photo-copying and recording, or in any information storage

Principles Of Technical Writing

Table Of Contents

Preface ............................................................................................... 1Over view of the chapters .................................................................. 1Introduction to Technical Writing .................................................................................................... 1Software Development Life Cycle .................................................................................................. 1Documentation Process ................................................................................................................. 1Communication Products ............................................................................................................... 1Introduction to Technical Writing ........................................................ 1Definition .............................................................................................................2Skills Technical Writer should acquire ............................................... 2Technical Communication .................................................................................3Project Management ...........................................................................................3Teaching .........................................................................................................................................3Research ........................................................................................................................................3Software .........................................................................................................................................3Technical ........................................................................................................................................3Software Development Life Cycle ..................................................................... 4Introduction......................................................................................................... 4Software Requirement Analysis ..................................................................................................... 4Analysis of Software Design ...........................................................................................................4Software Coding ............................................................................................................................. 4Software Integration ....................................................................................................................... 4Software Testing............................................................................................................................. 4Software Release ........................................................................................................................... 4Software Maintenance ....................................................................................................................4Software development models .......................................................................... 5Linear Sequential model. ................................................................................................................5Introduction..................................................................................................................................... 6STUDY, RESEARCH AND INTERVIEW TO GET INFORMATION. .............................................. 6Documentation Planning.................................................................................... 6Purpose and Structure ....................................................................................................................7Assumptions about audience training: ............................................................................................7Planning a Document Content ........................................................................................................7Communication Products................................................................... 9User Guide ..................................................................................................................................... 9GENERAL FORMAT FOR DEVELOPING USER GUIDE.............................................................. 9Operation manual .............................................................................................10GENERAL FORMAT FOR OPERATION MANUAL ....................................................................10Reference Manual .............................................................................................10GENERAL FORMAT FOR REFERENCE MANUAL ....................................................................10Release notes ....................................................................................................11Installation Guide ..............................................................................................11GENERAL FORMAT FOR INSTALLATION GUIDE......................................................................11INSTALLATION PROCEDURE .................................................................................................... 11Proposals........................................................................................................... 12Proposal Writing Situation ............................................................................................................12Your Audience ..............................................................................................................................12Problem ........................................................................................................................................12

i


Solution .........................................................................................................................................12Costs ............................................................................................................................................ 12Capability...................................................................................................................................... 12Structure for Proposals................................................................................................................. 12Introduction ...................................................................................................................................13Problem ........................................................................................................................................13When Your Readers Define The Problem ....................................................................................13When Your Readers Provide A General Statement Of The Problem.......................................... 13When You Must Define The Problem Yourself .............................................................................13Objectives..................................................................................................................................... 14Product .........................................................................................................................................14Method.......................................................................................................................................... 14Qualifications ................................................................................................................................ 14Management................................................................................................................................. 15Costs ............................................................................................................................................15Business Plan ...................................................................................................15INTRODUCTION ..........................................................................................................................15Structure of Business plan ..............................................................................15Proposal Content ..........................................................................................................................15Introduction................................................................................................................................... 15Market Analysis ............................................................................................................................15Proposed Business .......................................................................................................................16Products Or Services.................................................................................................................... 16Business Site................................................................................................................................ 16Schedule....................................................................................................................................... 16Qualifications ................................................................................................................................16Budget ..........................................................................................................................................16Conclusion ....................................................................................................................................16Booklets............................................................................................................. 17Brochure ............................................................................................................17Tutorial / Training Guide .................................................................................. 17Reference manuals ...........................................................................................17User Reference Manuals ..............................................................................................................18Reports ..............................................................................................................18Scientific Research Reports ..........................................................................................................18Business Research Reports ......................................................................................................... 19Instructional Design ......................................................................... 19Instructional System: ....................................................................................................................19User Interface Design ...................................................................................................................19Technical Reports............................................................................................. 20Contents of a Document .................................................................................. 20Illustrations ........................................................................................................21Cross-reference ............................................................................................................................21Endnotes ...................................................................................................................................... 22Footnotes...................................................................................................................................... 22Audience Analysis ............................................................................................ 22Conduct an an audience analysis................................................................................................. 23Identifying Audience Characteristics ............................................................................................23Assessing Audience Objectives and Needs .................................................................................23Preparing the content ...................................................................................................................24While writing .................................................................................................................................24

ii


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

iii


Preface

This reference guide gives information about the different aspects involved inTechnical Writ-ing. This reference manual deals with the introduction to Technical writing, skills required tobe a Technical writer, understanding of Software Development Life Cycle (SDLC), Documen-tation Process, ISO, Capability Maturity Model (CMM), and general format for different tech-nical 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 Writershould acquire.

Software Development Life Cycle

This chapter provides information on the Software development life cycle anddifferent devel-opment 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 generalformat.

Introduction to Technical Writing

Organizations that develop Information Technology solutions like software with no supportdocuments to ease the use were seen in bad light as the end users found it extremely diffi-cult or rather impossible to work with them.The complexity involved in the usage of differentproducts and software solutions has created a need to provide information to understandthese Products or software’s better. The end users of these products and solutions need tohave enough information to utilize the features offered. This is where a Technical writer con-tributes. A Technical Writer develops communication products to help users understand theproduct or software solution better.

1


Definition

Technical writing is a specialized field that requires various skills - the ability to write clearlyand concisely, the ability to organize content, a good understanding of technical products andprocesses, and knowledge of numerous documentation productivity tools.2

A Technical writer should:

Understand the type of technical report you are writing

1. Keep information specific rather than general2. Match content to your readers' knowledge and needs3. Plan the sections and subsections you need4. Write your headings using strong verbs and specific nouns5. Write in plain English6. Use active verbs rather than passive verbs7. Maintain your average sentence between 15 to 20 words8. Restructure wordy phrases9. Write using simple words rather than complex ones

10. Avoid jargon11. Keep technical terms to a minimum12. Use diagrams, flowcharts and graphs13. Design a good layout to draw attention to key information14. 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 technologyinvolved in developing the product or software solution.

Technical Writers must acquire the following skills:

• Communication

• Project Management

• Teaching

• Research

• Software

2


Technical Communication

Technical Writer should adopt proper usage of language. Develop Interpersonal skills likeempathy, negotiation, persuasion, and ability to socialize. Technical Writers must also under-stand the nuances of interviewing because Technical writers should interview subject matterexperts (SME) and gather information from them.

Subject matter experts are domain experts who develop products and solutions. echnicalwriters must empathize with their readers, conduct an audience analysis in order to deter-mine their readers, be aware of their phantom readers.

Project Management

Technical Writers should learn to manage documentation projects, this requires understand-ing project management. Project management involves organization and time management.Technical Writers should organize all the aspects of document production, keep track ofproject 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 shapetheir documentation.

Software

Technical Writers should be well versed with the documentation software’s like Adobe Frame-maker, Adobe Photoshop, and Microsoft word. Knowledge of one documentation softwaremakes it easier to learn the other. Technical Writers with knowledge of RoboHelp can createversatile online help manuals.

Technical

Knowledge of one or more programming languages makes the Technical Writer useful foremployees. 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 thereby be an asset to the employer.

3


Software Development Life Cycle

Introduction

In order to understand the documentation process prevalent in organizations, it is necessaryto understand how the software development life cycle works. This is necessary as documen-tation process orients itself with the software development life cycle.

Software Requirement Analysis

The business development team collects information from the customer. An exhaustiverequirement 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 todesign the software. The software is broken down to manageable components called mod-ules. 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.Thesoftware is subjected to alpha testing. After the software has passed the alpha testing. Thesoftware 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


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 con-sists of

• Analysis – Analysis of Requirements

• Design – Design of solutions

• Coding – Development of solution

• Testing – Test the solution developed for flaws before

Requirement

Analysis of

Coding

Testing

Release

Maintenance

Documentation

Integration

5


• Analysis Design Coding Testing

• Documentation Process

Figure 2: Linear Sequential Model

Introduction

The process involved in developing a technical manual usually involves team effort. In mostsituations, a Technical Writer or Technical Communicator is only given one portion of thewhole 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 communica-tor, 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 read-ing the document.

b) Write for one audience group at a time and indicate which group you are addressing.

Analysis Design Coding Testing

6


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 backgroundinformation?

Planning a Document Content

After analyzing the audience and choosing the appropriate medium for the document, planits 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


Figure 3: Documentation Development Life Cycle

Study Existing Information - SRS

Interview SMEs

Draft Table of contents (TOC)

Review Process - Peer Review - Documentation Manager Review - Functional Mangers’ Review or

Engineering Department Review - Customer Review

Write based on the approved TOC

Complete first level document (25%)

Complete Second level document (75%)

Complete final document (100%)

Release

8


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 solu-tions.

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 likeCopyright, registered trademarks, service marks, license agreement details, license ownerdetails, Partnership agreements, and disclaimers. Acknowledgements Brand Uniqueness,Safety features (in case of Hardware products)

1. Contents2. Introduction3. System Requirements4. New Features5. Audience6. Getting started or quick guide7. Information to experienced users8. Alternate help features9. Technical support10. Security11. Contents based on user interface or task12. General reference13. Supporting technical information14. Source15. Trouble shooting16. Glossary17. Index

9


Operation manual

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

GENERAL FORMAT FOR OPERATION MANUAL

1. Heading with organizations details2. Disclaimer, copyright information, suitability criteria, limitation of warranty 3. License agreement4. Contents5. Introduction6. Installation details7. Configuration8. Setup for fitness testing9. Background preparation in case of Bio-engineering systems10. Customization11. Usage12. Reporting formats13. Deliverable format14. Troubleshooting15. Communications16. Compatibility17. Miscellaneous18. Appendix19. Index

Reference Manual

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

GENERAL FORMAT FOR REFERENCE MANUAL

1. Preface or Front matter2. Order Number3. Overview4. Standards Conformance5. Compatibility6. Contents7. Introduction8. Basic features9. Complexities or Uniqueness

10. Commands or Procedures11. Variables12. Features13. Control14. Using past references

10


15. Installing the software16. Reporting bugs17. Discussion on obsolete features18. Index19. Index of commands20. Index of reserved words21. Parameter and variable index22. Function index23. Concept index

Release notes

Release notes contain release information, version enhancements, known issues, and bugfix. 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. Product logo, Organization notes, general communication2. Contents3. Introduction4. Documentation Convention, How to use this document? Recommended Configuration,

System compatibility, Installation prerequisites

INSTALLATION PROCEDURE

1. Steps to get you started2. Where to find supporting information3. In case of software, Memory compatibility4. Customizing installation5. System Upgrades If failed6. Trouble shooting7. Support Actions

11


8. Additional Support9. Additional options

10. Index11. 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 inter-ested in it. What problem, need or goal your proposal address - and why is it important tothem?

Solution

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

Costs

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

Capability

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

Structure for Proposals

Conventional superstructure presented here must be consumed as a general plan. You mustuse your imagination and creativity to adapt it to particular situations.

Proposal can contain the following headings

12


• Introduction

• Problem

• Objectives

• Product

• Method

• Resource

• Qualification

• Management

• Costs

Introduction

Tell your readers what you are writing. Announce what you will be proposing. Postpone thefull 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 willaddress some problem that is significant to them. Although you can persuade your readerthat your proposed project will achieve its objectives and that its costs are reasonable, youcannot hope to win approval unless you show that it is worth doing from your readers’ pointof view. You must not only identify a problem but make it interesting to your readers. Notonly define a goal but make its achievement seem worthwhile to your readers. To do thisrequires both creativity and research. Furthermore, just how you describe the problem willdepend 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 theywould like your firm to solve. In such situations your primary objective is to show your read-ers 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 helpyou formulate the problem. Some of the questions you need to keep in mind are How youcan make your proposed project important to your reader?What goals or responsibilities doyour readers have that your proposal will help them achieve?What concerns do they typically

13


express that your proposal could help them address? A good place to think is from efficiencyand profit.

Objectives

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

Product

When you describe the product of your proposed project, you describe your plan for achiev-ing the objectives you have listed. To describe your product persuasively, you need to dothree 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 byensuring that your objectives grow directly out of your statement of the problem, and thatyour product will address those objectives directly.

Method

The readers of proposals need to be assured that you can, in fact, produce the results thatyou promise. Especially in situations where you are proposing to do something that takesspecial expertise. To assure themselves the readers will look for.Your method or plan ofaction for producing the result.

The facilities, equipment, and other resources you plan to use.

1. Your schedule.2. Your Qualification.3. Your Plan for managing the project.4. 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 thatthe proposers have the experience and capabilities to carry it out successfully.

14


Management

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

Costs

As emphasized throughout this write-up, when you propose something, you are asking yourreaders to invest resources, usually money and time. Naturally, then, you need to tell themhow 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 theattention of a discerning venture capitalist. Business plan offers the necessary information tothe investors.

Structure of Business plan

Proposal Content

For details on Proposal content, refer to the proposals section under the communicationsproducts chapter.

Introduction

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

Market Analysis

Provide persuasive evidence that market exists for the business you are proposing. Who willbe your end users? What are the important characteristics of these people from the point ofview of your proposed business? Also discuss any compeFundamentals of Technical Writingtition that exists and explain how you can compete effectively against it. If you cannot talkabout any competition then talk about a similar business that has been tried in your commu-nity but has failed.

This chapter has to be as long as is required to persuade your readers that a substantial mar-ket exists for the business you are proposing.

15


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 servicesdirectly to your market analysis.

Business Site

Discuss in detail the physical layout of your business with explanations as to how this wouldmake 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 yourbusiness. Begin with approval of your proposal and continue to the point where your businessis 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 notexceed one page.

16


Booklets:

Booklets are generally more extensive than brochures, they convey introductory or overviewrather 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 productor 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 insertfrequent headings to mark major topic divisions.

Tutorial / Training Guide

A tutorial uses explanations, repetitions, hands on, practice, exploratory learning and othermotivating methods to help the reader attain a desired skill level.

Typically, tutorial / training guides are produced either as stand alone documents or as partof 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 completetechnical details about its operation. They are not task-oriented and are organized alphabeti-cally, numerically or by product features.

A Reference manual shows how a system is designed and operates. For example, the refer-ence manual for a multiple-line telephone system may contain writing schematics andswitch-setting tables of interest to technical but not to telephone users.

Many reference manuals are multipurpose and serve the needs of installation, operations andmaintenance personnel. However, a complicated system may require a separate referencemanual for each task or component.

17


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. Whilemost user guides address only primary tasks, a user reference manual describes everythinga user can do with a system.

User reference manuals generally includes both procedures and concepts as well as a refer-ence sections, effective headings, cross references and a good index help readers who oftenhave varied technical background and experience, find specific information.

User reference manual should be task oriented, because it must be complete informationsource.

Reports

Reports which answer a question or offer a solution to a problem, generally support fourbasic 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 audiencesare 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 forsuch 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 founda-tion 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 tableswith accompanying narrative explanation, present this data objectively and without interpre-tation.

18


7.Conclusion: Discuss and interpret the results.

8. Appendix: provides additional information such as data, they may be inappropriate withinthe text.

Business Research Reports

Business research reports provide data and answer questions to support making an impor-tant 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 wordsthat can assist in searching for the published report.

Executive Summary - Summarizes the center report in one page or less emphasizing therecommendation 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 problemor situation.

Recommendation and Conclusion- Propose a detailed course of action.

Appendix- (if necessary) provides additional information, such as data that may be inappro-priate within the text.

Instructional Design

Instructional design is the systematic development of instructional specifications using learn-ing and instructional theory to ensure the quality of instruction. It is the entire process ofanalysis of learning needs and goals and the development of a delivery system to meet thoseneeds. It includes development of instructional materials and activities; tryout and evalua-tion 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 bothlarge 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 isthe systematic process of developing instructional systems and instructional development isthe process of implementing the system or plan.

User Interface Design

Many technical innovations rely upon user interface design to evaluate their technical com-plexity to a usable product technology above May not in user acceptance and subsequent

19


marketability. While product engineers focus on the technology, usability specialists focus onthe user interface for greatest efficiency and cost effectiveness. This working relationshipshould 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 accep-tance and rejection in the market place. If end-users feel it is not easy to team, not easy touse or cumbersome; an otherwise excellent product could fail.

Good user interface design can make a product easy to understand and use, which results ingreater user acceptance.

Technical Reports

1. Understand the type of technical report you are writing.2. Write down your specific aim3. plan the section and subsection you need4. Avoid starting with background, introduction and methodology5. Writing your headings using strong verbs and specific nonus6. Match content to your leaders knowledge and needs7. Keep the information specific rather than general8. Write in plain English 9. Use active verbs rather than passive verbs

10. Keep your average sentences between 10 to 20 words11. Edit wordy phrases12. Use simple words rather than complex ones13. Avoid Jargon.14. Keep technical terms to a minimum.15. Use examples and illustrations.16. Use diagrams, flowcharts and graphs.17. 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


8.User non-textual elements (graphics, charts, equations) that are necessary for clarity areIllustrations.

Illustrations

Illustrations can be used in a variety of documentation types from job training material toproposals, 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 toread or Speak a language other than English

Cross-reference

Use cross reference to provide guides to related information. There are two types of Cross-references, See and See also

In the See cross-reference all the information related to a term is included within anotherterm. 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 relatedinformation. See also cross-reference often point from the general to the specific, as well asamong 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


Endnotes

Endnotes are similar to Footnotes, except endnotes are grouped together at the end of theentire 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. Usea 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 mean-ings given to the following sentences by placing only in different positions.

Footnotes

Footnotes are the traditional and accepted method for citing and documenting sources inmany disciplines.

Place footnotes at the bottom of the page on which the reference occurs. A superscriptednumber follows the reference in the text.

Also place the number followed by the author’s name ant the rest of the bibliographic infor-mation, as in an endnote.

Footnote place references close to the text they support. This placement eliminates flippingfrom 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 abibliography.

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


Conduct an an audience analysis

Conduct either a formal or an informal audience analysis. Use formal methods to gatherquantifiable 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 as-

1.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 readsthe 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 thedocument.

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


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 prod-

uct.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.

4. Focus on a few main points5. Make the structure evident6. Announce, explain, review7. Clearly signal the transitions: listeners can have difficulty when you shift from one topic

to another8. 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.

24


13. Use shorter, simpler sentences than you might use when writing14. Pick words your listener will immediately understand.

How Visual Aids Help

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

25


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


INDEX

AAids 25Analysis 15BBooklets 17Brochure 17Business 19Business Plan 15CCoding 4Communication 2Communication Products 9Contents 20Cross-reference 21DDesign 19Documentation 6EEndnotes 22FFootnotes 22GGuide 17IIllustrations 21INSTALLATION GUIDE 11Instructional 19Integration 4Interface 19LLinear 5MMaintenance 4Management 3manuals 17OObjectives 14OPERATION MANUAL 10Oral Presentations 24

27


PProblem 13Project 3Proposals 12RReference 17reference 1REFERENCE MANUAL 10Release 4RELEASE NOTES 11Reports 18, 19SSoftware 4Software Development Life Cycle 4Structure 12TTechnical 1, 3Technical Writing 1Technology 1Testing 4Training 17Tutorial 17UUser 19USER GUIDE 9VVisual 25

28

Documents

Technical Writing Manual