Sei sulla pagina 1di 33

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 ............................................................................................... 1
Over view of the chapters .................................................................. 1
Introduction to Technical Writing .................................................................................................... 1
Software Development Life Cycle .................................................................................................. 1
Documentation Process ................................................................................................................. 1
Communication Products ............................................................................................................... 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 Writ-
ing. This reference manual deals with the introduction to Technical writing, skills required to
be 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 Writer
should 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 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 diffi-
cult 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 con-
tributes. 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. Keep information specific rather than general


2. Match content to your readers' knowledge and needs
3. Plan the sections and subsections you need
4. Write your headings using strong verbs and specific nouns
5. Write in plain English
6. Use active verbs rather than passive verbs
7. Maintain your average sentence between 15 to 20 words
8. Restructure wordy phrases
9. Write using simple words rather than complex ones
10. Avoid jargon
11. Keep technical terms to a minimum
12. Use diagrams, flowcharts and graphs
13. Design a good layout to draw attention to key information
14. 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 under-
stand 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 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 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 Frame-
maker, 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 documen-
tation 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 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.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 con-
sists 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 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.

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 Interview SMEs


- SRS

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 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 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. Contents
2. Introduction
3. System Requirements
4. New Features
5. Audience
6. Getting started or quick guide
7. Information to experienced users
8. Alternate help features
9. Technical support
10. Security
11. Contents based on user interface or task
12. General reference
13. Supporting technical information
14. Source
15. Trouble shooting
16. Glossary
17. Index

9
Principles Of Technical Writing

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 details


2. Disclaimer, copyright information, suitability criteria, limitation of warranty
3. License agreement
4. Contents
5. Introduction
6. Installation details
7. Configuration
8. Setup for fitness testing
9. Background preparation in case of Bio-engineering systems
10. Customization
11. Usage
12. Reporting formats
13. Deliverable format
14. Troubleshooting
15. Communications
16. Compatibility
17. Miscellaneous
18. Appendix
19. 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. Preface or Front matter


2. Order Number
3. Overview
4. Standards Conformance
5. Compatibility
6. Contents
7. Introduction
8. Basic features
9. Complexities or Uniqueness
10. Commands or Procedures
11. Variables
12. Features
13. Control
14. Using past references

10
Principles Of Technical Writing

15. Installing the software


16. Reporting bugs
17. Discussion on obsolete features
18. Index
19. Index of commands
20. Index of reserved words
21. Parameter and variable index
22. Function index
23. 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. Product logo, Organization notes, general communication


2. Contents
3. Introduction
4. Documentation Convention, How to use this document? Recommended Configuration,
System compatibility, Installation prerequisites

INSTALLATION PROCEDURE

1. Steps to get you started


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

11
Principles Of Technical Writing

8. Additional Support
9. Additional options
10. Index
11. 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 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 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 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 pro-
posed 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 achiev-
ing 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. 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 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 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
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 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 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 refer-
ence 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 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 tables
with accompanying narrative explanation, present this data objectively and without interpre-
tation.

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 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 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 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 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 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 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 com-
plexity 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 accep-
tance 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. Understand the type of technical report you are writing.


2. Write down your specific aim
3. plan the section and subsection you need
4. Avoid starting with background, introduction and methodology
5. Writing your headings using strong verbs and specific nonus
6. Match content to your leaders knowledge and needs
7. Keep the information specific rather than general
8. Write in plain English
9. Use active verbs rather than passive verbs
10. Keep your average sentences between 10 to 20 words
11. Edit wordy phrases
12. Use simple words rather than complex ones
13. 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
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 Cross-
references, 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 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 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 infor-
mation, 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 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 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 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 points


5. Make the structure evident
6. Announce, explain, review
7. 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.

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. 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 say
5. 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

Potrebbero piacerti anche