Software

Documentation

Chapter One

Understanding Task Orientation

1
 Software Documentation

Def:
Is a form of writing for both print and online
media that supports the efficient and effective
use of software in its intended environment.

Software Documentation Forms:

Print Users Manual
Installation Guide to the online help program
Wizards
Tutorials
getting started booklets
2
Importance of Software Documentation
It help software users learn program features
and use them to work productivity.

Fatima M. AbuHjeela
It contributes significantly to the value of the
software product.

It contributes to the users efficiency in the

work place.

It aims to supporting experts ,guiding and

teaching beginning and intermediate users.
3
 Writing software documentation
Guidelines

Fatima M. AbuHjeela
Understanding task Orientation.

The Forms of Software Documentation:

Writing to Teach (Tutorial).
Writing to Guide (Procedures).

Writing to Support (References).

4
 Writing software documentation
Guidelines
The Process of Software Documentation:
Analyzing your Users.

Fatima M. AbuHjeela
Planning and writing your document.
Getting useful reviews.
Conducting usability tests.
Editing and Fine tuning .

The tools of Software Documentation :

Using Graphics.
Getting the Language Right.
Layout pages and screen.
5
Designing Indexes.
 Understanding Task Orientation

Def:
Is an approach to software documentation that
present information in chronological order based on

Fatima M. AbuHjeela
the users workplace sequence .

It encourages the successful application of

software to workplace objectives.

6
 Understanding Task Orientation

Understanding task Orientation helps Software

Documentation writers to achieve two goals:

Fatima M. AbuHjeela
Encourage the users to learn the program
(Proficiency)
Encourage the users to apply the program to
problem in the workplace (Efficiency)

o It adapt the software to the users job, rather

than making the user adapt to the software.

7
o It make the software usable.
 Task-oriented Documentation
When we describe a manual as task oriented this
mean:
It helps the user to manage and communicate information

Fatima M. AbuHjeela
related to his or her task.
Users can clearly see the relation between new program
and their work place.
Task-orientateddocumentation consists of manuals and
help that reflect real users and human forms.
The process of task-orientateddocumentationrequires that
you analyze the user in his or her work environment to
discover the rich texture of activities within the software
8
program and where the manual fits.
 Guidelines for Successful Software
Manual
1. Emphasize problem solving:
A manual should help users solve problems in their

Fatima M. AbuHjeela
workplace.

You can help the user through introductory paragraphs

that preview not only the steps to follow, but the goals
and objectives of their software work.

Example:

9
Guidelines for Successful Software
Manual
2. Provide Task-Oriented Organization:
Organize a manual or help system in a way that matches

Fatima M. AbuHjeela
the kinds of tasks a user will perform.
Example:
A word processing manual that follows the open a file,
type in words, save the file, exit the program . The
sequence would seem more logical than one organized
alphabetically.

A task oriented arrangement should be spread all over

the design of your manual from the table of the content
( of your manual) or the introductory screen ( of your
help system ). 10
 Guidelines for Successful Software
Manual
3. Encourage user control of Information
This mean the feeling , among software users, that they decide
what the program does for them.

Fatima M. AbuHjeela
So, the manual should show users how to make key decisions,
supply key information, or determine key program outputs.

Cross references in manual and hypertext links in online

system can help maintain the users sense of control over the
documentation , because these document design elements
allow users to choose where they go for additional information
,or where to proceed after they have finished a section.

11
 Guidelines for Successful Software
Manual
4. Orient pages Semantically:
Semantic Orientation in page design means you

Fatima M. AbuHjeela
arrange the elements of the page meaningfully
according to elements of the job the user needs to
perform.

Example:
Putting important elements first and making
important elements larger to help user apply the
program to their work.

Employs visuals and graphic to text in a

complementary way. 12
 Guidelines for Successful Software
Manual
5. Facilitate Routine and Complex tasks
Users of software face two types of task :
1. Routine Task:

Fatima M. AbuHjeela
Repeatable tasks that are easily represented by conventional
procedures .
Example:
Save a file, print a file , open , and so on.

2. Complex task
Require the user to apply knowledge that is not easily codified
in step by step procedure, it comes from years of experience.
Example:
Using a word processor to identify trends in annual reports .

The more you can help users apply software to complex tasks the 13
more users will value your manual or help system .
 Guidelines for Successful Software
Manual
6. Design for Users:
User driven design means manual comes from the user
needs rather than from models or templates of what a user

Fatima M. AbuHjeela
guide should look like.

User driven design should allow users to :

1. Find what they need.
2. Understand what they find.
3. Use what they understand appropriately.

14
 Guidelines for Successful Software
Manual
7. Facilitate Communication Tasks:
Users of software programs work in context that require them to
communicate about their work.

Fatima M. AbuHjeela
Communication tasks depend on the users workplace demands
rather than on a narrow view of program features.

Document designer should know what kind of

information users communicate and to whom
and help them achieving this.

Document designer can help the user see the

why behind the program features by analyzing
what kind of info user needs and how they
communicate.

15
Communication tasks are facilitated by tasks that transfer data
from one application to another .
 Guidelines for Successful Software
Manual
8. Encourage user Communities
Task oriented manuals encourages users to identify and
get helps from others. Some software has some features

Fatima M. AbuHjeela
that encourage group or team work.

Other users of the program ,while not exactly experts in

the software ,cab render valuable help because they
understand the users job demands.

User communities can help provide candidates for this

kind of user-involved document development.

16
 Guidelines for Successful Software
Manual
8. Encourage user Communities

Fatima M. AbuHjeela
17
 Guidelines for Successful Software
Manual
9. Support Cognitive Processing
People always use mental model cognitive schema-, that
help them learn, process, and apply the information.

Fatima M. AbuHjeela
Task oriented manuals uses principles of knowledge
representation, parallelism and analogies to convey
software features to workplace.

These techniques (analogies and parallelism) allow user

to absorb what manual has to say with as little effort as
possible.

18
 Guidelines for Successful Software
Manual
The good manual or help system has many
features that make it succeed ,

Fatima M. AbuHjeela
But

The more a manual can support productive work,

the greater the chance of acceptance and
satisfaction by a user.

19
 Goals of the Software User and
Manual
Goals of the user:
1- Learn how to use the program.
2- Apply the program to useful work.

Fatima M. AbuHjeela
Goals of Manuals or Help screens:
1- Support the features of the program.
2- Tell how to apply the program to the users job.

20
 Task Orientation

Def:
A design strategy for software documentation that

Fatima M. AbuHjeela
attempts to increase user knowledge of and
application of a program by integrating the software
with the users work environment.

21
 Task Orientation
When a user sees that learning and using a
program can increase job efficiency ,most will
take time to read the manual and read the

Fatima M. AbuHjeela
program.

The full potential of a manual is realized when

technical writers take an approach to develop
documentation( online and on paper) that
models the natural cognitive processes of users
who are seeking to fill knowledge gaps through
the right information ,presented at the right
time ,and in the right place to meet task goals. 22
 Software User Types

User :
Is a person who operates a computer.

Fatima M. AbuHjeela
There are two ways to define the user of any
software:
1. The Default User:
a person who needs to learn about menu

functions and commands.

An operator instead of thinker.

2. The Task-Oriented User: 23

A person who uses software for workplace ends.
 The default User Characteristics
1. Decreased importance of job skills,
My experience isnt good any more.
Job deskilling: which means that the computer program can

Fatima M. AbuHjeela
perform many of the tasks a person used to perform, so the
job required less skilled people .
The default user is the user who lets the computer do it

2. Increasingly abstract tasks,

I just cant understand how this thing works.
. People have trouble seeing the link between doing by hand
and doing with a computer lies to the abstract
nature of computer work.

. Feeling of loss of control over their work, user feels that it 24

loses most of its simplicity.
 The default User Characteristics
3. Increasingly isolated from other employees,
Im stuck in front this computer.
People need others to communicate with, to get

Fatima M. AbuHjeela
feedback from, and to get rewards that make work
enjoyable.

4. Remotely supervised, My boss has an

electronic leash on me.
The default user feel increasingly exposed to the
manager.

They may lose their sense of control over their work,

because of the increased supervision exercised 25
through computer system.
 The default User Characteristics
5. Overloaded with information, why do I need
to know that?, information anxiety.

Fatima M. AbuHjeela
They resist computer use because they feel
overloaded by information.
Having too much information without the
ability to understand its significance can
cause information anxiety.
This causes many users to restrict their use
of software and give up trying to learn and
apply it .
26
 The Task-Oriented User
Characteristics
1. Challenged by skill demands: This program makes
me a better user
Require user to engage in complex tasks, that
require human mind and sophisticated knowledge.

Fatima M. AbuHjeela
Computer can sort and categorize ,but it cant
handle ideas.
The manual must points the user in the right
direction.
Computer activities (using word processor) require
actions (writing a letter) and operations (opening a
file, setting a margin, checking spelling, selecting a
font..).

27
The task-oriented manual instructs to action
level ,rather than the operation level.
 The Task-Oriented User
Characteristics
2. Conceptually Oriented
This gives me something new to think about
Difficulties when using computer that you

Fatima M. AbuHjeela
have to
learn more than your actual work. (For
example you have to learn internet security,
encryptions etc when you use a billing
application program).

This information is called Tacit knowledge,

because it is not easily represented by steps.
28
The Task-Oriented User Characteristics

3. Aware of user communities:

For those user using the same program.

Fatima M. AbuHjeela
User groups: refers to groups that meet,
electronically or in person, to discuss
issues related to their job activities.

Allow users to increase their social

contacts within an organization and
overcome the sense of isolation they may
feel.
29
 The Task-Oriented User
Characteristics

4. Information Rich : My software help me sort

out my work.

Fatima M. AbuHjeela
Good software documenters should find ways
to reinforce workplace skills by showing
users the potential use for information that
programs generate.
It can open users up to a new kind of tasks.

30
 User Types
1. Novice Users:
Initial users of a program ,or novice users of
software in general.

Fatima M. AbuHjeela
Require tutorial documents, the intension of
which is to teach basic functions and their
applications.

2. Intermediate Users:
Require procedural documentation.

The intension of which is to help them during

actual use of the program in their workplace. 31
 User Types
3. Advanced Users:
Require Reference documentation .

The intension of which is to further their

Fatima M. AbuHjeela
understanding about how the program
operates and how they can manipulate and
adapt it to highly specialized uses.

32
The Forms of Software documentation

1. Tutorial Documentation:
. Intends to teach a basic functions and
features of a program to a user .

Fatima M. AbuHjeela
. The user motivation is to learn.
. The relationship between the writer and the
user resembles that of a teacher and
learner.
. Define the tasks through : sample scenarios,
examples of usage, demonstrations, etc .
. Focus on basic actions that the user can
take.
33
 The Forms of Software documentation
1. Procedural Documentation:
. Intends to guide the user step-by-step procedures for
using the program(often when the user needs
information at the time of use).

Fatima M. AbuHjeela
. The user motivation is perform action tasks.
. The relationship between the writer and the user
resembles that of a guide and mentor.
. Define the tasks through : tips and help embedded in
the user interface, context-sensitive help available at
the click of the mouse, wizards that assist users in
performing difficulties .
. Focus on operations organized around workplace
actions.
. Employs many tools to help users in actual use of the
program ,including step-by-step procedures, 34
suggestions and tips and descriptions of fields .
The Forms of Software documentation
1. References Documentation:

. The user motivation is to obtain information about

the program for advanced user.

Fatima M. AbuHjeela
. The relationship between the writer and the user
resembles that of a resource and client.
. Lets the user define the task.
. Focus on the descriptive of the program itself than of
the user or the users application of the program.
. Example: alphabetical listings of program features,
lists of examples, file formats, technical
troubleshooting data and special program settings.

35