technical writing

1. STRUCTURING VARIOUS
DOCUMENTS
By :-GEETA HINDWAR

2. User guide
• An user guide provides information about using the product.it usually
contains the theory and concept about the feature/product and instruction
for using the feature of the product.
• Some such the user are
• Students(MS word, Photoshop)
• Web designer(flash, Dreamweaver)
• Image editor(Photoshop)
• The user using the user guide rely on it to get answer to most of their
question about the product.
• So you have to keep in mind the perspective of the user and focus on their
requirement when creating users guide.

3. Organization and structure
• Provide an overview of related topics and point the reader to the reference
manuals or tutorials for detailed information.
• These manuals are usually organized by task or by topics.
• Each chapter should begin with short introduction.
• The first section should ideally be an overview of the topic to be discussed.
• Use task oriented heading and section title.
• Use numbered and bulleted lists to help reader scan the information
quickly.
• Follow the rules of parallelism.
• Use table to provide statistical information and other details ,information
presented in tabular form to access.
• Use graphics to show the reader the key concepts of the objects they will be
working with.
• The user guide usually update for major releases. This reduce the effort
for updating the large manuals and the cost of updating ,publishing and
distributing the document again.

4. content
• The user guide contains information that show the users the proper way to
use the product by including appropriate information.
• Details and basic information about complex concept for beginners.
• Instruction and step by step procedure to help the new users accomplish
their goals without having wade through a lot of information.
• Specific details that the user wants. Tell them how to do certain takes and
why is should be done ,rather than what the options in a panel are for.
• Explain commands and controls in the context in which they are used.
• If there are several to choose from(explains when to choose the options).
• A complete list of limitation (if appropriate).
• Special notes such as warning ,cautions and notes to alert the reader
regarding any potential problems or emphasize special points.
• Troubleshooting tips and alternative approach to solve the problems.

5. Tutorial guide
• Tutorial are nothing but solved examples. Each tutorial explains a particular
feature of the product.it may contains sample problems that demonstrated
how to use the features of the products.
• The goal of a tutorial is to help the users and advanced users. Keep in mind
the perspective of the user and focus on their requirement.
• Audience-have a different approach of writing for new users and advanced
users. Keep in mind the perspective of the user and focus on their
requirement.
• Organizational structure:-each tutorial being with a short introduction that
tells users what they are going to learn using that tutorial .

6. Continue……
• Organizational structure:-each tutorial being with a short introduction that
tells users what they are going to learn using that tutorial .
• Mention the prerequisites required for the tutorial.
• If the particular tutorial require an add on or if you need the activate
certain license to run it, mention it upfront.
• Steps involving selection of one option over others should ideally have a
comment that explains why that option should be selected.
• Provide details in areas where the user might ask why they need to do
something to perform the action.

7. CONTENT
• The content tutorial should cater to specific set of users.
• The introductory tutorial are written for new user. Hence it should explains
all the steps in details.
• Advanced tutorial should follow a similar format with less details. You can
assume that advanced user are familiar with the basic elements of the
product.
• For most product only the first tutorial provides explicit instruction for
every step. The remaining tutorials assume that the user is familiar with
common tasks, so can skips the explicit instruction unless the task is new
,unusual or less frequents used.
• Try to keep the instructions close to related panel figure, so that users can
easily refers to the panel while following the steps.

8. WRITING STYLE
• Use instructional style of writing.
• Use you not the user or one to refer to the user.
• Use numbered lists as this is a procedural writing.
• Steps should be written in the imperative form.
• Examples:- incorrect-the ABCD option can be selected in this panel.
• Correct:-select the ABCD option.

9. INSTALLATION GUIDE
• An installation guide contains the procedure for installing a soft
ware.it is usually written in the end of the documentation
development life cycle.so it may not be given adequate time for
review and usability testing causing the errors to creep in.
• Audience:- the audience can range from system admiration who
have experience administering complex system to engineers who
have considerably less experience installing software.

10. Organizational structure
• Organize the book so that it contain separate section for platform
specific information. Do this is instruction differ widely between
operating systems.
• Include separate information for the different
platforms(HP,IBM,SUN,SGI).
• Installation guide should usually have five main topics
:system,requirements,installation,confriguration,llicensing, and
troubleshooting.

11. CONTENT
• The most common problem is that the user cannot install the product
properly. Technical writer can solve this problem by writing clear
installation instruction designed to install the product and get it working as
soon as possible. Apart from the other information also add the following:
• Hardware ,software, database and network requirements.
• Description of system setup and configuration for the first time users of the
software.
• Precautionary information such as notes ,warning caution, and even danger
notices where ever appropriate.
• Trouble shooting related tips and instruction to solve common problems
that can arise during installation.
• Writing style:- use numbered list whenever possible to describe a
procedure. Use terminology that different groups of user can understand.

12. Release notes
• Release notes lists the new features in major or maintenance release,
without going into any details. The release notes refers users to user’s guide
for information about the new features. Sometimes limitation are listed in
the release notes (not in the users guide).ideally ,every release, major and
minor should have release notes.
• AUDIENCE :-most of the user use the release notes to learn about
functional improvement, new functionalitites,limitation,and setup changes
in the software.
• ORGANIZATIONAL STRUCTURE:- release notes is
organized such that it contains information using which the user get an idea
about the product. Suggested topics for release notes include:
• New features
• New and updated configuration options
• Limitations

13. content
• The release notes contains the following type of information:
• Introduction for new product release or upgrade.
• Description of new features of the product.
• Known issues by suggesting work around.
• Limitation if any.
• Writing style:- use a balanced style for release notes. Use task
based procedures, itemized lists and descriptive writing(to introduced
overview information about the upgrade).

14. Getting started manual
• The getting started manual is actually a booklet included in the standard
product package.it include basic information about the product and instruction
for using the documentation cd.it is generally update only for major release.
• AUDIENCE:-the getting started manual are written for user who may not
have specific technical knowledge.it will give them overview about the
product, without having to wade through all the details in the user’s guide.
• Organization and structure:-the getting started manual is organized
such a way that:
• the information is short and concise ,approximately 100-150 pages.
• It explains the purpose of the product and summarizes how the product works.
• Dose not give too much information .instead it points to the users guide for
more information.

15. content
• The getting started manual contains the following type information:
• Explanation regarding the purpose of the product.
• Summary about how the product works.
• The basic installation information(sometimes).
• Description of the basic work procedure, but not in detail.

16. Reference guide
• When user need quick reminder how to proceed with a certain task ,they
may not even think of using a bulky and detailed user guide. Research
shows that in such situation users are forced to use the user guide often
resulting in decreased productivity.
• Quick reference guides can help avoid such situation.to create effective
jobs aids, create effective page layout containing the key information the
user may require. Skilled technical writers will know what kind of
information they have to extract from the subjects matters experts and will
communicate the necessary information to the user.

17. ADDENDUM
• An addendum is the booklet that contains information about new features
that are added to a product since its previous release. the addendum is
created or update when ever there is a maintenance release with new
features. This document provide information about features that are not
documented in the user guide. That is those feature added to a product for a
maintenance release that dose not warrant update the user guide.
• This way there is no need to update the entire user’s guide and perform the
production tasks for printing it, or publishing it online. This information is
later incorporated into the users guide, during the main release. Use the
same format and style as in the user guide.

18. Functional specification
• A functional specification describes the intended capabilities ,appearance
,interface ,behavioral characteristics and other details of a planned
functionality of a product.
• Organization and structure:-
• Overview containing brief description of product improvements.
• Summary of requirements (functional ,goal ,sub goals ,limitations).
• Correlation of features to requirements.
• How the feature is used.
• Interaction with other parts or functionalities of product.
• Interactions with other products ,if applicable.

19. CONTENTS
• The functionality of the application or product should ideally cover the
information regarding the following:
• Window layouts(with illustrations, if possible)
• menu item used
• Button description(as appropriate)
• Syntax (for an API specification)
• New users interface additions and changes(with illustration ,if possible)
• Changes to existing GUI(with illustration, if possible)
• New and /or changed mouse behavior.
• Help topics that are added and /or changed
• Shortcuts to perform task (hot-keys),if any.
• Constraints such as assumptions ,dependencies and risks.
• Internationalization issues.

20. Online help
• Online help requires different organizational skill than what is required to
create the user manual or other conventional manulaus.in this case the
information must be much more concise and to the point. Ensure to use.
• Lists (bulleted and numbered )are used as much as possible.
• Tabular formats where possible.
• A good search facility.
• A good and usable index.