Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
Training Manual
Course Module 1
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
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.
This chapter provides information on basics of Technical writing and skills a Technical Writer
should acquire.
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.
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
Technical Writers must have a flair for writing and capability to understand the technology
involved in developing the product or software solution.
• 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
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
Introduction
The business development team collects information from the customer. An exhaustive
requirement analysis is done and documented in Software Requirement Specifications.
Software Coding
The different software modules are developed based on the design document.
Software Integration
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
Software Maintenance
4
Principles Of Technical Writing
Requirement
Analysis of
Coding
Integration
Testing Documentation
Release
Maintenance
Software development life cycle in its simplest form called the linear sequential model con-
sists of
5
Principles Of Technical Writing
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.
The technical writer collects the information from the subject matter experts.
Documentation Planning
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
3. Can the document assume the audience has a group of basic concepts of background
information?
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.
7
Principles Of Technical Writing
Review Process
- Peer Review
- Documentation Manager Review
- Functional Mangers’ Review or
Engineering Department Review
- Customer Review
Release
8
Principles Of Technical Writing
Communication Products
• 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.
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.
Reference Manual
Reference manuals offer quick information about the procedures to be followed, in order to
complete the user’s tasks.
10
Principles Of Technical Writing
Release notes
Release notes contain release information, version enhancements, known issues, and bug
fix. Release notes suggest workarounds possible.
Installation Guide
INSTALLATION PROCEDURE
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.
venture capitalists.
Your Audience
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?
Conventional superstructure presented here must be consumed as a general plan. You must
use your imagination and creativity to adapt it to particular situations.
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.
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.
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.
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.
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.
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
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
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.
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.
Reference manuals
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 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.
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 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.
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
8. Appendix: provides additional information such as data, they may be inappropriate within
the text.
Business research reports provide data and answer questions to support making an impor-
tant decision or taking specific action.
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.
Appendix- (if necessary) provides additional information, such as data that may be inappro-
priate within the text.
Instructional Design
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:
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
Contents of a Document
1.Clearly states the purpose, providing a explicit justification for the 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
5.Provide visual relief for a page heavy with text and sometimes replaces text
1.Perform procedures
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
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.
1.Interrupt the readers by directing their attention to the note at the bottom of the page.
3.Do not provide a collected resource –as endnotes do – unless they are accompanied by a
bibliography.
Audience Analysis
22
Principles Of Technical Writing
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
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.
Before you begin writing identify and consider such important audience characteristics as-
4.Reading context the physical and psychological conditions under which the audience reads
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.
23
Principles Of Technical Writing
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.
4.Organize hierarchically.
While writing
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
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:
Impromptu talk: one given on the spur of the moment with little or no preparation.
24
Principles Of Technical Writing
13. Use shorter, simpler sentences than you might use when writing
14. Pick words your listener will immediately understand.
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:
Philip Rubens; Science and Technical Writing-A manual of style; 2nd edition, 2004.
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