Text preview for : A260 A New Approach to Diagnosis Information; Mutimer.pdf part of IBM A260 A New Approach to Diagnosis Information; Mutimer IBM share SHARE_61_Proceedings_Volume_1_Summer_1983 A260 A New Approach to Diagnosis Information; Mutimer.pdf
Back to : A260 A New Approach to Di | Home
~SHARE~ SHARE SESSION REPORT
A260 A NEW APPROACH TO DIAGNOSIS INFORMATION 200
61
SESSION NO. SESSION TITLE ATTENDANCE
SHARE NO. 2
STEVE WINCKELMAN PSU
DOCUMENTATION
SESSION CHAIRMAN INST. CODE Abstract
PROJECT
Igg02ENNSYLVANIA STATE UNIVERSITY ZIU COMPUTER BUILDING UNIVERSITY PARK, PA. In keeping with task-oriented library design, ffiM is now publishing diagnosis information to provide
a basis for effective communication between the user and the ffiM Support Center. Problems are
SESSION CHAIRMAN'SCOMPANY, ADDRESS, AND PHONE NUMBER diagnosed based on their symptoms. The objective of diagnosis information is to relate those
external symptoms to a functional area of the program.
The speaker will describe the organization and content of two books - the diagnosis guide and
diagnosis reference. These books complement each other and are intended to increase the produc-
tivity of the people involved in the resolution of program failures.
Introduction
The first set of diagnosis books were published in 1977 for IMS/VS. Now, at least twenty ffiM
program products have diagnosis books in their libraries. The titles and formats have evolved, but
the concept is unchanged.
I have personally worked on this concept for six years - I have written several of these books, and
now spend full time consulting with other writers who are developing diagnosis information. So
why is the title of this session, "A New Approach to Diagnosis Ioformation"? Diagnosis informa-
A New Approach to DIagnosis Information tion is not new to many of you. Diagnosis information remains a "new approach" after six years
because it is so very different from the information it replaces.
<.D
00 Diagnosis information is a "planned" method for locating the cause of a program problem. It does
not require full knowledge of the program - that knowledge is built into the methodology. Diagno-
Jeannette Mutimer sis becomes just another task, much like installing or using the program.
I can still remember when I was in class learning to program. I had barely Iearned the assembler
ffiM Corporation language, and the instructor moved on to a high~levellanguage. It was a long time before I was
555 Bailey Avenue comfortable that coding one statement would handle so many details. You may feel a similar anxie-
San Jose, California 95150 ty about the difference in the amount of information between the program logic manual and the
diagnosis reference.
I have three objectives today. First, to ensure that "diagnosis" is not "new" to you; to make you
comfortable with the contents and organization of the diagnosis books; and to make sure you
DOCUMENTATION PROJECT understand how to use diagnosis books to increase your own productivity. Second, I want to con-
vince you to use diagnosis books to resolve program problems. And third, I want to invite you to let
me know how well they work for you.
Session Number A260
To meet these objectives, I will digress a bit to explam the concept of task-oriented libraries. I will
also review with you our analysis of the diagnosis task. For it was this analysis which set the stage
for packaging the information. I then will talk about the organization and contents of the diagnosis
guide and diagnosis reference, and review a scenario of how to use these books to resolve program
problems. I will conclude with a discussion of the merits of diagnosis information and the contrib-
ution these books can make to your productivity in performing the diagnosis task.
4
Task-Oriented Libraries DiagllOJfis Task Analysis
IBM's task-oriented libraries are geared to the activities people perform using our products. An The scope of the diagnosis task is, in reality, doing whatever is necessary to keep a program productive. To
overall goal of task-oriented libraries is to be "task-sulficient." bring this into focus it is necessary to establish boundaries.
Writing task-sufficient information presents some interesting challenges. It means that all informa- Defmition of the Task
tion must be pertinent, and information must be collected in one place. Of course, the information
must be complete and accurate - but there is a degree of completeness and a degree of accuracy The diagnosis task begins, by definition, whenever an mM program is suspected of not functioning correct-
that is not pertinent to the task. ly. This definition assumes that there is reasonable evidence to suspect a software failure. The information
in the diagnosis books does not address hardware problems. The definition also assumes that the program
How do we know what is pertinent? First, we must understand the task. There is seldom only one has been used correctly - although it may tum out that the problem was caused by a user error.
way to do anything, so we must make some decisions about how the task will be performed. For
example, if each of us were to give directions about the route to get to this hotel from the airport, Diagnosis books deal with software problems, and software diagnosis typically begins with the symptoms,
we would not all give the same instructions, although we all accomplished the task. We conld, how- and tracks back to the cause of the problem, using the symptoms as clues. What may appear to be a soft-
ever, combine our directions to describe a route that would work for everyone. All of us would not ware problem, may, in fact, be caused by an obscure user errllr, or a hardware problem. But tbat fact must
agree that it was the best route. What is important is that the directions are straightforward with as usually be revealed by the same diagnostic processes that locate code problems.
little room for error as possible. The directions must accurately describe the complete route, but the
directions need not describe every intersection in that route. Completeness and accuracy to this Task Activities
degree would complicate rather than simplify the task.
Within the scope of this definition we separated the diagnosis task into five activities, as shown in the figure
The basis for designing a task-oriented library is a task analysis. In this analysis, each major task is below. As I mentioned earlier. diagnosis is unique in that mM shares the responsibilities with its customers.
examined to identify the significant activities in the task, and a plan is developed that describes the Some of the responsibilities overlap, and others belong either to mM or to you, mM's customers. Let's look
<...> steps required to accomplish those activities. The task analysis becomes the criterion to evaluate at how the activities in this task relate to the people who will perform them.
<..0 appropriateness of information during the writing of the manual. If there is any doubt about the
completeness, or the need for any portion of the content, that question can be answered by match- Keep in mind while we go through this analysis, that we are setting the limits for both the information that
ing the iulormation against the requirements of the task. Likewise, if a piece of information appears will be included, as well as what will be excluded, in a task-sufficient library.
to be valuable, but does not map to the task analysis, then the analysis itself is reexamined.
I. Identify the Source of the Problem
The Diagnosis Task
The diagnostician is responsible for identifying the component in control at the time of the failure.
Diagnosis is only one of the "tasks" supported by a task-oriented library. But diagnosis has three
characteristics not common to other tasks. The diagnostician is principally you, ffiM's customer, although an ffiM representative may also assist in
that process. I use the term "diagnostician" to identify everyone who participates in the preliminary
1. Diagnosis involves the same basic activities for all programs. investigation of the problem.
2. A single problem could easily cause you to use books from several product libraries. 2. Describe the Problem
3. This is the only task that requires interaction between IBM and its customers. The objective of this activity is to investigate a problem sulficiently to be able to describe it with a set of
keywords.
Because all the activities are essentially the same for all program products, the information can be
organized in the same way, even though the contents are product-specific. I am sure you will agree A large percentage of program problems experienced in the field are already known, are described in the
that consistency in organization is particularly helpful when books from two or more product software support data base, and are corrected. The challenge for the diagnostician is describing prob-
libraries are used simultaneously. lems consistently, so that known problems can be distingnished from new problems.
6
4. Report New Problems
If a similar problem description is not found, or the problem being investigated cannot be resolved with
an existing correction, the problem is reported as a new problem. The objective of this activity is to
ensure that the problem is accurately described and the necessary supporting documentation is gathered.
Diagnosis The IBM Support Center Level 2 representative reviews the information obtained by the diagnostician
and may suggest additional investigation. Level 2 will confirm that the keywords used to search the data
Task base describe the problem accurately. Level 2 is also responsible for creating an APAR (Authorized
Activities Program Analysis Report).
The primary responsibility of Level 2 is to act as a problem manager - that means applying the appro-
priate expertise at the appropriate time to resolve a problem expeditiously.
5. Correct New Problems
The change team is responsible for locating the cause of the program problem and making the necessary
corrections to the code: When the problem is corrected, they place a description of the problem and its
Software correction in the software support data base. If the same problem is experienced by another user, its
Support description will be found during the search of the data base.
Data Base
....... Members of the change team are ffiM's product experts. For some products, the same individuals per-
o)
L form both the Level 2 and the change team activity, but have different responsibilities depending on
which role they are performing.
Things are seldom as simple as this characterization suggests. These "activities" depict the intermediate
results that lead to problem resolution. The objective of the diagnosis documentation is to direct you in
achieving these results.
Information Packages
The purpose of going through the task analysis with you today is to give you a better understanding of what
to expect from task-sufficient diagnosis books. You really need to know very little about the analysis in
order to use the books effectively.
3. Search for Similar Known Problem
The conclusion drawn from the task analysis was that three types of information were involved.
The quickest way to resolve a problem is to find a ready-made solution. So the next activity is to search
the software support data base for a similar problem description. 1. Precise guidance information for the predictable activities.
The ffiM Support Center Level I representative will search the software support data base, using the For each program product we can predict what information is vital