Chapter 1 - Lecture 1

Software Documentation
Dr. Hani Bani-Salameh
Department of Software Engineering

The Hashemite University
[email protected]
Req. Development Testing
Specifications
- Functional * Design Implementation -

- Non- * UML •Code -
IDEA Functional Diagrams comments - SW is delivered
- Domain •Use Cases -
- System •Class
•Sequence
At this phase, documents are
needed by the users in order
to be able to understand the
Architectural Test SW.
SRS Design cases
Document Document
•Tutorials
•References
•Procedures
Course Objectives
 This course prepare the students with such

writing skills that are interested in:
 Finding practical steps to help them start and complete
their projects successfully.
 Exploring ideas behind software documentation as a
discipline and as a profession.
Organization of the Course
 Part-1 (The forms of software documentation)

 Introduces the concept of task orientation,
 Introduces the forms of Software Documentation such as Tutorials, Procedures,
and References.
 Part-2
 Describes the task-oriented software documentation process.
 Part-3
 Describes the software architecture documentation process.
Introduction to Software
Documentation
 What is Software Documentation?
 Why we need Software Documentation?
 Who uses Software Documentation?
 How we develop Software Documentation?
 When we develop Software Documentation?
 Where do we start?
Chapter 1:
Understanding Task Orientation
Guidelines for a Successful Manual & Help
System
 Chapter Objectives
 Helps the software documentation writers to achieve the following two

goals:
 Encourage users to learn the program (proficiency)
 Encourage users to apply the program to problem in workplace (efficiency)
 Always focus on one principle:

Make the software easy to use and usable.
Software Documentation (Definition):
 A form of writing, for both print and online media that supports
the efficient and effective use of software in its intended
environment.
 A written text or illustration that accompanies computer

software. It either explains how it operates or how to use it, and
may mean different things to people in different roles.
 Task Orientation (Definition):

 An approach to software documentation that presents
information in chronological order based on the user’s
workplace sequences.
 A design strategy for software documentation that

attempts to increase user knowledge of an application
program by integrating the software with user’s work
environment
 Any software documentation (manual) that shows
the connection b/w the user’s work and the
program can be described as “task oriented ”.
 A manual that does the above, adapts the software

to the user’s job, rather than making the user adapt
to the software.
 Scenarios and example contribute to that.
 Task Orientation encourages the successful application of
software to workplace objectives.
(It focuses on helping the user clearly see the relation
between the program and their workplace.)
 This approach to documentation is shown in variety of print

and online forms:
 Tutorials
 Procedures
 References
 Strategies that encourage task orientation
1. Emphasize problem solving
2. Provide task oriented organization
3. Encourage user’s control of information (think about Scenarios)
4. Orient pages semantically
5. Facilitate both routines and complex tasks
6. Design for users
7. Facilitate communication tasks
8. Encourage user communities
9. Support cognitive processing
Strategy 1: Emphasize Problem Solving
 The manual or help system should help users solve problems

in their workplace.
 The problems may be kind of (Examples):
 How can I organize this project?
 Where and how can I find this specific data?
 How can I complete this specific task?
 In “introductory overview” you can help the user not only
recognize the steps to follow, but also the goals and
objectives of their software. (slide 11)
Strategy 2: Provide Task-Oriented
Organization
 Organize a manual or help system in a way that:

 Matches the kind of tasks a user will perform.
 Follow the sequence and not in terms of a alphabetically
arranged menu.
 Example:
 A word processing manual that follows –
 Open a file – type in words – save the file – exit the
program.
Strategy 3: Encourage User’s Control of
Information
 Users should feel in control of the program. That means:

 Users must decide what the program can do for them. It
should not be the other way around.
 The document should show users how to make key
decisions, supply key information, or determine key
program outputs.
 Example: Specifying what a database program will search for

and identifying which data the program will process.
Strategy 4: Orient Pages Semantically
 Semantic information in page design means that you

“arrange the elements of the page meaningfully, according to
elements of the job the user needs to perform.”
 Ways to orient pages semantically include:
 Putting important elements first
 Using larger fonts
 Employing visuals and graphics to balance text in your
documents.
 This makes it easy for the user to understand and perform the
job in a better way.
Strategy 5: Facilitate both routine and
complex tasks
 Routine tasks
 Repeated tasks that easily represents the conventional
procedures
 E.g. save file, open file, delete record … etc.
 Complex tasks
 These tasks require user’s knowledge (that comes from
experience) to apply.
 E.g. using a spreadsheet software to calculate employees
salaries, and identify their performance in annual reports.
 If the manual helps users to perform complex tasks, it will be valued
more by them.
Strategy 6: Design for Users
 The design of a manual or help system should be based on

users’ needs rather than from templates of how a manual
should be arranged or should look like.
 User-driven manual design should allow:
 Find what users need
 Understand what they find
 Use what they understand appropriately.
 Thus, user-driven design needs an extensive user analysis.

Chapter 1 - Lecture 1

Uploaded by

Copyright:

Available Formats

Chapter 1 - Lecture 1

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Chapter 1 - Lecture 1

Uploaded by

Copyright:

Available Formats

Software Documentation

Dr. Hani Bani-Salameh

Department of Software Engineering

- Functional * Design Implementation -

 This course prepare the students with such

 Part-1 (The forms of software documentation)

 Helps the software documentation writers to achieve the following two

 Encourage users to learn the program (proficiency)

 Encourage users to apply the program to problem in workplace (efficiency)

 Always focus on one principle:

Software Documentation (Definition):

 A written text or illustration that accompanies computer

 Task Orientation (Definition):

 A design strategy for software documentation that

 A manual that does the above, adapts the software

 This approach to documentation is shown in variety of print

 The manual or help system should help users solve problems

 Organize a manual or help system in a way that:

 Users should feel in control of the program. That means:

 Example: Specifying what a database program will search for

 Semantic information in page design means that you

 The design of a manual or help system should be based on

You might also like