Introduction to SD

What is Software Documentation?

Why we need Software Documentation?

Who uses Software Documentation?

How we develop Software Documentation?

When we develop Software Documentation?

Where we start?
A manual that does this can be called “ task
oriented”, because it helps the user to manage
and communicate information related to his or
her work

we will explore on this course the techniques

that can help you create a manual or help
system that focus on helping the user clearly
see the relation between the program and their
workplace.
 What is task-oriented documentation

• Task-orientated documentation is really the challenge of

creating documentation that looks at the process of writing and
finds ways to learn about users.

• Task-orientated documentation consists of manuals and help that

reflect real users and human forms.

• The process of task-orientated documentation requires that you

analyze the user in his or her work environment to discover the
rich texture of activities within the software program and where
the manual fits.

• This book has the technical communicators goal in mind--to be an

advocate for our readers!
Guidelines for Successful Software Manual

1- Emphasize problem solving:

The manual should have the goals and objectives of
the procedures and steps to follow to solve problems
in the workplace.

In “introductory overview” you can help the

user not only in the steps to follow, but the
goals and objectives of their software.
2-Provide Task Oriented Organization:

Task orientation should be spread all over the design

of your manual. (from the table of contents and on),

So, organize your manual or online help in a way that

matches the kind of tasks a user will perform, such as
open a file, type in words, save the file, and exit the
program.
3-Encourage User Control of Information:

This means the feeling among users, that they

decide what the program offers for them.

Show the user how to make key decisions, supply key

information, determine key program output.
4-Orient Pages Semantically:
Arrange the element of the page meaningfully
according to the elements of the user need to
perform.

Put important element first, larger fonts, and employ

visuals and graphics to balance the text in your
documents.
5-Facilitate Routine and Complex Tasks:
Routine task include repeatable tasks that are easily
represented by conventional procedure such as (save a
file, delete a record..).

Complex tasks require the user to apply knowledge

that is not easily codified in step by step procedure.

This knowledge consists of insider info that comes

from years of experience.
6- Design for Users:
User driven design means manual comes from the
user needs rather than from models or templates of
what a user guide should look like.

User driven design should allow user to:

- find what they need.
- understand what they found.
- use what they understand appropriately.
So user driven design, needs an extensive user
analysis. (chapter 5)
7- Facilitate Communication Tasks:
- Document designer should know what kind of
information users communicate and to whom
and help them achieving this.
8-Encourage User Communities:

Task oriented manuals encourages users to identify

and get helps from others. Some software has some
features that encourage group or team work.
9-Support Cognitive(known) Processing:

- People always use mental model –cognitive schema-, that

help them learn, process, and apply the information.

- 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.
Goals of the User:
1- Learn how to use the program.
2- Apply the program to useful work.

Goals of Manuals or Help Screens:

1- Support the features of the program.
2- Tell how to apply the program to the user’s jobs
Task Orientation:
A design strategy for software documentation that
attempts to increase user knowledge of applications of
any program by:
integrating the software with the user’s work
environment.
The default (computer-Mediated) User:
- A person who uses software for workplace ends, an operator
instead of thinker.

- Computers not only do work for us, they record information

about the work. (grocery store scanner, print receipt, update
inventory, may be update some flags for statistics).
Characteristics & Difficulties (face default user)

Different Needs & Preferences:

People want different things from a system or product. Some need simplicity, others
want lots of options.
Different Skill Levels:
Some users are tech experts, while others need more guidance or help.
Speed & Convenience:
Users usually want things to work quickly and easily. They don’t like waiting around.
Emotional Reactions:
How a system looks and works can make users feel happy, frustrated, or confused.
Access to Tech:
Users might be using old phones or slow internet, which can affect how they use a
system.
 Hard-to-Use Interfaces:
If the system is confusing or hard to navigate, users get stuck.
Slow or Buggy Systems:
Users don’t like waiting for things to load or dealing with crashes.
Not Personalizing the Experience:
If the system doesn’t adapt to the user’s needs, it might feel
impersonal or awkward.
Lack of Help:
If users can’t easily find help when they need it, they get frustrated.
Not Accessible for All:
Users with disabilities (like vision or hearing problems) might struggle
if the system isn’t designed for them.
Security Concerns:
Users worry about their personal data being safe. If security isn’t
clear, they may not trust the system.
Unclear Errors:
If something goes wrong and there’s no clear explanation, users get
confused.
The Task-Oriented User:

1- Challenged by Skill Demands:

- This program makes me a better user.

- The higher level skill require the human mind.

- Computer activities require actions (writing a letter) and

operations (opening a file, setting a margin, checking spelling,
selecting a font..)
 2- Conceptually Oriented:
- This gives me something new to think about.
- Preference learning, some people have an easier time
learning abstract concept, others learning with analogy.

- Difficulties when using computer that you 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)
 3-Aware of User Communities: for those user using the
same program.

User groups refers to groups that meet, electronically or in

person, to discuss issues related to their job activities.

4- Self Managing:
- My software help me sort out my work.
- The program will do this and you can do this with the
program.
 5-Information Rich:
- My software gives me a better view of my tasks.

- Information has become the currency.

- Those who control information about production statistics,

deadlines histories can use it to acquire important resources or
plan effectively.
Three types of document can be created
for each type of user:
• Tutorial documentation: intends to teach the basic functions and
features of a program to a person can begin applying the
program to workplace tasks. Examples: getting started guides
and online tutorials.

• Procedural documentation: intends to guide the user in

everyday use of the program, often when the users need
information at the time of user. Example: step-by-step
procedures.

• Reference documentation: intends to supply information

"about" the program to advanced users that rarely consult the
user's guide or tutorial but occasionally need to look up
information about the program. Example: alphabetical listings
of program features, lists of examples, file formats.
 User Assistance
- User assistance is a general term for guided assistance to a user of
a software product. The phrase incorporates all forms of help
available to a user.

- User Assistance can also automatically perform procedures or step

users through the procedure, depending on the question that
the user asked.

- User assistance provides information to help a person to interact

with software.

- The term is broader than online help, and includes procedural and
tutorial information.
 The processes of software documentation.
• It really begins by exploring what users are using the software for;
again, taking that human approach.

• This is a process of exploring user needs and then of constant

involvement of the user in the process of writing and testing (this
process is called usability process).

• Users and their needs drive the writing. Please see Figure 1.8 for the
different stages of writing software documentation, which include
the planning, development, and evaluation stages.

• Finally, “A manual that integrates a software program into the user’s

environment has a better chance of getting used than a manual that only
documents the features of the program.” Words of wisdom for all of us.
Guidelines to construct your task list and
task description:
1- Determine the right level of detail:

- Who will write the document, individuals or

group (with group you may want to go into
greater detail).

- What kind of interface do you have, the more

complex the interface the more details you
need.
- How much experience do the writers have (less
details needed for expert because their knowledge on
the system and standards, more details needed for new
members on the documentation team)

-What is the stress level of your project, do you need

to produce it quickly? You may have a time to
perform a level one list, and then fill in the step later.
Major elements of task description are:

a- Task Name, categorizing tasks, ex. transfer a file.

b- Steps, larger program, ex. select transfer from the file

menu, select the desired file, click the transfer button.

c- Options, complex interfaces, ex. switch to another drive,

cancel the transfer operation.

d- Screen, complex interface, ex. show screen.

Task Name: setting up a chart.
User: end user.
Starting state: MS chart is open, the user has created a spreadsheet
document.
Goals state: the parameters of the chart are set and it has plotted.
Steps:
1. Choose the chart type.
Options:
line chart icon: selects the line chart
Bar chart icon: select the bar chart
2. Type the chart title.
3. Type the vertical scale title.
4. Type the horizontal scale title.
5. Choose the values to be Plotted.
Options:
1st row: set value for first row
2nd row: set value for second row.
3rd row: set values for third row.
11. Click the plot button.
2-Categorize the program tasks:

- End use, tasks put the software to work, starting

program, processing, sorting data, quitting, open a file,
search for a record.

- Installation, tasks get the software onto the user’s

system, copying program from distribution media,
uncompress programs that have been compressed to
fit on disks, running the installation program.
- Configuration, tasks get the software set up
right, set up the software so it will work in the
user’s hardware environment. Customizing,
setting options, setting preference.

Some programs may combine installation and

configuration in one task.
Characteristics of a task:

a- Independent.
b- Short duration twelve steps or less.
c- Goal oriented.
d- Has starting and ending points.
e- Made up of steps.
f- Often relates to a menu function.