FRAME: A Concept for Documentation at ABB Data

(1)

FRAME· A Concept for Documentation at ABB Data

Lars Hemingstam

Kreativ SystemUtveckling, Stockholm, Sweden

Traditional models for systems development offer little, or no, guidance concerning the production of end-user documentation.

Anyone who is starting to write end-user documentation runs across many initial problems. Is there an ideal stmcture for a manual? How should the page layout be designed?

What is the best way in which to describe an on-line dialogue? How can I engage the end- users in the documentation process?

FRAME is the result of an ambition to describe system applications from the end-users' point of view. The concept has been developed by ABB Data during 1987-88, with the par- ticipation of end-user representatives in three pilot projects. Several additional documentation projects using FRAME have been completed since then and still more will be completed during 1989. The reactions from writers as well as end-users have been very posi- tive.

The concept consists of general recommendations for a documentation project, stan- dards for presentation of common functions, such as integration of infonnation between systems and on-line dialogues, as well as technical support for producing documentation in an IBM VM/CMS environment.

•

(2)

THE PROBLEM

"This is how our new system will make your work easier."

(

There are many tools and methods support- ing systems development, but how do you present the result - the system and its advan- tages - to the end-users, reference-group members and company management?

When system documentation is produced, at all stages of the development process, much effort is by tradition concentrated on describing facts correctly and defining logical relationships in more or less technical terms.

Elementary pedagogical considerations and presentation techniques are often neg- lected.

Intricate flow-charts and system configu- ration diagrams are readily included in end- user documentation, with the intention of clarifying matters, even though few end- users are trained at interpreting the charts.

Communication between the system developer and the end-user is thus often carried out on the terms of the developer.

Itis certainly no simple task for the system developer to present the output of an analysis in a way that is easy to understand and relevant to the end-user.

(3)

(

A SOLUTION

FRAME is a concept for documentation deve)o)led by ADD Data.

The FRAME concept consists of two main parts:

1 Rules and recommendations for organizing a documentation project, structur- ing the contents of a manual, editing texts, layout considerations, etc.

2 Technical support for producing documentation using IBM CAP technique in a VM/CMS environment (DCF/Script and 4250, 3820 or 3812 laser printers).

The goal for developing FRAME has been to find a way in which to describe a system application from the end-user's point of view.

FRAME is now used by ABB Data for producing manuals for end-user applications, but is also intended to be used for writing pilot studies, system specifications, etc.

(4)

ABB Data

ABB Data offers its clients (the companies of the ABB Group) solutions to functionally oriented problems.

An end-user in one of the ABB companies is most often a user of several system applications, e.g. construction systems are integrated with production- and purchasing systems and the end-user functions can span over these system boundaries.

In many cases the end-user is not even aware of the fact that he/she is switching between different applications when carry- ing out operations.

New corporate organization

When the decentralized organizational stmcture of the ABB Group was implemented, the experienced central staffs of the parent company no longer existed, and the staff functions were to be carried out by inde- pendent ABB companies.

This created a great need of better infor- mation concerning ABB Data systems to many new end-users with little or no experience of the applications.

From this need of a total review of the existing documentation, the FRAME project emerged in May 1987.

FRAME

As the name indicates, FRAME is main- ly a tool, or frame, for presentation. FRAME can be regarded as a link between the development environment and the end-user environment.

The concept was developed by a project group during 1987-88 and involved defining the following items:

• The activities of a documentation project.

• The structure of a manual.

e

Text editing recommendations.

• The documentation layout.

• The publishing technique.

• Organizing documentation main- tenance.

• Introducing the documentation to the end-users.

Three application systems were used as test cases - a purchasing system, a project administration system, and a system for quality control.

Every phase of the development process was presented to the reference groups of the test projects for approval.

As a result of the FRAME project, ABB Data has obtained a standard for end-user- oriented documentation, to be used through- out the system development process.

l

(5)

The technical writer

At an early stage the FRAME project group found that producing documentation is a full time task for a specialist.

The need for a technical writer function has been recognized in industrial production for many years, but the same need is .not commonly acknowledged when devel- 'oping administrative system applications.

ABB Data has now formed a special group of technical writers. The writers also act as project leaders for the different documentation projects.

The technical writer is as essential as the programmer, the system analyst, the project leader and any other specialist if a development project is to become successful.

A documentation project

The documentation project runs parallel to the system development process.

In a separate pilot study for the documentation project, the following is defined:

• Which functions that are to be

described. This is thoroughly checked with a reference group of end-users.

• Different reader categories; their characteristics (such as previous EDP- experience, general level of education, etc) and thus their documentation requirements.

In the production stage the writer describes each function, chapter by chapter.

Describing functions as seen by the end- user is the foundation for FRAME documentation.

This is done in an over-view manner using written scenariosorcase studies and in a detailed manner by describing functions in the end-user's business/production environment and relating the system to these functions.

To accomplish this it is necessary to:

• Define the relevant functions.

• Describe them in the correct step-by-step order.

• Relate them to surrounding activities.

• Use the same temlinology as the end-user.

This is made possible by close co-opera- tion between the technical writer and a reference group consisting of end-users and system developers.

The reference group studies, alters or gives approval to the texts produced by the technical writer. The reference group checks that the texts can be easily understood by none-EDP-professionals and that the facts are correct.

The introduction stage is just as impor- tant as the previous stages. For new applications the manual is distributed in connection with the initial tTaining courses. For existing applications a special introduction meeting is arranged for the end-users to get ac- quainted with the manual.

(6)

The documentation structure

The structure of the documentation is designed to make it possible to produce tailor- made manuals (across system boundaries) for different categories of end-users and to facilitate easy-to-understand explanations of system integrations.

Every function (as defined from the end- user's point of view) is described in a separate chapter. By combining selected chapters from different manuals, a category of read- ers can obtain a manual that is designed for their special requirements,

The documentation layout

A great deal of effort has been made to design a standardized layout in order to make the contents easy to read and to understand, and to gain efficiency in the documentation process.

Using FRAME, many initial problems that arise when producing documentation have already been solved, and the writer can concentrate on creating the text.

The standardized layout also applies to step-by-step examples of on-line conversa- tions, simplified flow-cham illustrating paths between menus and panels, and stan- dards for describing reports and screen layout.

(

:;.":":~;:-:"';...... u." ..·~

2~'~:..:";:~':;:' ':.'~''" ,., ..,£" .•.LA ... ,,,' ••••••

f',~". , ..f1"~1.1" -.1I .", ...'0'"'~'l•• 1'_" ..·..", 1.>_

.",1nil '"~"".1" ~".,rl . SJ Ai,Xii,nil"ii,^f)/t.111filllll'JrtfA'~r."..."J."

,~:'~Dt ^':';ii 'i!~:{"~~!~(i~~ i!,)!" ,-

FunkUoner Ikopanmodankon

7,2

nOlO]

12.2

nO)l!

Orderllorplan • PM29

. - - -

--_. . _ - - -

"'" ~:: ~:'.~'::".~'\:::,"'.:~~

..

^,^..^, ^,:::.^'"

...".. ,....-.""~.,,.. :"'-... -.... rn...

'I :r,:I :~~ I:~~:';~~v;:o..

:mI 1;::1 :'~:J::::::::

!.,

ⁱ

: ::;:: :~:: :l::::;:~, ~.=

,_I.. r;., ,... , ...", ... _.._::~:l", .""_1):::

._.",

::::f=::~;:

^•..

^'" ^:II

:; :::: ::.:: : ::-:r'J,-':'-;::'

" ""1 ."" I'... .,..,·.,.·.. , I

:: ::::, ::m ,w:t..-::.,~..: :'

:: ::::: ::::: :::':~::. :

" ,m, '"'' '."... ,,, '"

.... _.. tOO •••• .. ..

1".11...11<,.,,.j,. "..Jr".t..,..I.'" •• ,,, l~,.1",,, ",. it,,,",,, t:/0".." "...r..."n....hn tf&t:~

."",II~~".I"."..,..."I"••""III,,,h'..'\url ~:

"Hll .

l:,~:'.~':;~.. ::::..!~..,;...u:c:~: ,,,".... ,. "^I

... .... n" ."' ,",' .. ..

.... ,... ", ..,. ... ""0-... ",, ,

~:~::s:\:-:.

...

t~:::~ "'F::ilfi:ii!~"'~":r:'~"

1....11~ ,.,,~. . .~....ohl. ...." ..",.... '01"1I~r , 11_;h

1""\ Ill... l' =Y

1.1·"""ItI....""."."'·1,," ...'.. a~~

,~:.~::..':';.::".,:."

..,..-

,~..

.:;:. ,,,r;:---

,..~

,,,,. "'" , ,"'..,,, ,,,.,, .",

"", "...'~ "..",

...

^"., "',""

!:!

jlmi~mj~¥:?·

,,·

ji~; .! i!

"",:, '::1-::::~:~:::::::;.;':...

:r::=' "':",' "

"":':

';1::::·~~~If:::~:

:""

":;;~:':

"':' ":' ::

Oil-line dia/oglles are described by mealls of step-by-

.."w."".;:;";:;""."",;;;,.;;:..;;;:,~o-^{_ _}-"A",!,""O",ala ---~'"~o~.,"'c

Reports are retrievedfrom list files 10 be illcll/ded ill

(7)

Visa besfiillnlng

12.1

Manuel! faklurerlng PU51

11110'

Fllllkllon~h('"'\krhnjug

n"fh "rrtit rU'I-(.. ,mu'.i. ""nm.1I'~';H l'I'~1I r 1t,\N. "'h r",i"ll.,!dr'''lt~'<il"

.1,,,,"1, II" r A r."'t'

FAI.INAM:"i FOIlKI,ARIW;

''''

..

^'^...,.".",

....

^~.

....'""·.~I·JV;...

01.'01:... ,III '.110H!'.· "III '!",\" oliO

I.·.•,~lt'" 11.11;:'l'~ 1,.",.','0· <If, l.'~·'"

IlLl'JO~, rIlISt~l/'Il,I'"", 'I ".

1111:

r'l_>0;...., ,,~. 'lI'l~IOI"'\IDI>~ r n . l l " I '

.,!-~'~11'1 ... '101 'Ill'.,u^{t ...},~,,,, "11-~"r"f''''',''1°'''',0>

, ..~"I'll n.o",DI\".~'~.""t·M\·"'I~

IIDIIi."1 1)<_"l'OI'" ,~.It"l'" '~"l"("I1.n}'lI'.I.)

r""Fl'"0 : " ' " ~{'" 'f'0 '('{~".~;'ro'Olh'~

t411'('" l"".'!(IO!

'·11

.

"II^,~

KUlIDtm """"~~mm.'.11.,m,.,,~'n~...m..

",ISV k"'ln,d,':ill. <nli" r l'Ok-r..",..1

SLAO ",,"n..h,I.~tnl,tl I PoK'(",m,1

SUI!IUSUO SuI>· ..::h~nJr"lJl>·numm..

IVII fllJTO: •• ""UII!'I"" Ht~<{.};••

r.nFi' ,OI>OJ Uil'I(W/: ((.

C'tJIO 'Olsu.n~ ~-lIl'!'~.\IJO f;1lJ t •• ""11-1111

11 1"", 'Ill»1<">01 1~.l'·1 ,01 I".~'I'./II

(;<.{, I',\~,00"\\1'" t"H.IJlI,'N'

SIl!V~ "Wfo;"( "".1"1 1".'."'J ,)()

Il.,l.n I,,,. ,-"

n.... "\ '" ,n""

.... n.I . . , , , " . , ,

1,",,'"11

U" II, II...r,·"~'"

.'1 ...,.Il~·.·r"1)" .",

.!IN

II"u."l)""U", "':(lfrl' Il",ill •.' h r l ...~.. "'",

")",, 'rr"i"""1,,

U I . "...'"",.·"' ...,

.' 1"\"r"'""I1"''''

11 .~.t"r''''''''

I~,I." .,'1 ••\o,...lh ... h .Il" ,,,h.,,,I, HI' .i ••" '",,'~I.I.,M I.,,,N' I' .. I,,, I"n.l"w,~lie.,.',I''''''rrM, ,,, II ." ~¥,I.

[:~',:::':~;>~~';,:;;,'~,;;~';."'rr...'"_I '" I ,..,t . . "..J, •• "

'MI'''''''"">tll'rr' /i,""

U ~".l<l"" ",,, r1 II,,',"","'...

(

'"

t·0110 OElOPP OELISLUlnJU·

LAGO

r"'dulll' .... r.-,. "pl'fi"·I,"i"1

II.;'.n,."I)~ h\-"',~!"",,,...r.-",nI .",,1..

n.l"rr

I(.,>droi,1M",,' 1'1.1)In·Io'ul f,,,~It«.1",,,_.f"I'IIft!·

'''''''.'u'r--\urf"I'.'~<1

ADOO!!,".'- ====~~

"'lo.b ••'.!!~I~g 'l-~ PLUTO

/lBB 0'11<1

Simplifiedflow-c1wrls show the recol/ullellded working order.

Stalldardized descriptiolls offields alld screell lOyDIlls.

8.1

nOlO)

Reglstrera besllillnlng

kopanmodan ( CI704 ) Lonerapporlering 9.1

nDlI)

[t

^Il.

--- -.- -.-- --- ----. _.---

n.,,,~"r, h"~,pd,... '" ,.,",,~ "",.,....~"I' Ir~UM~(-.Blll.11"

r~.'" ...-~^IJ" ^{1 ...}1I~ 11't~1l1' , "' ••

\'14 '"II, ,.1':1>"u.<>I',~."...,~'I".""" ."...ulIt"II'"''\'.1 .."'"""n..."

,II,1t ....<1.1••.11... "'''I"III~,u.",,,t, .,..n",~

\'I~.1110, .11" 1I.1t1o lo" ..>dIlIl"",.,..IIMII1It1 ....'".ri",1'10,.,..,,,•...,,... ,...h_4 1.11.(I,",.,Uri.ro.H H'''....-.... l''''''~.l'''''''_I.

._----- . -- ~ - - - ~ - _ .- -- .- - -- - - _ . -

~h(,f1>ild

L-[[(}->

~~~

[rJQ.~~>

[~~:.:>

foil. 1"1''''''''"''.'' '.." ...,.n '",."".",.,1 ....,.,,,, "'" d••", f;',~::'~~,"...';\';l;;;:~I'l ,~,.~~: '~~r:;',:;.::,~;:',~ ~;~';.:.'~·~,,'~:~Ij,_

"Il,l1a:Oj'

II" I,,, "I""'" ,on<n1'1""""",1" I,ll en f-o,u.lIr,., ".,d"

'GI'"n ..-.l."I~"'II. ,"f.""."II., ,," ',.h. min" "1'(',>11"

"" I"","n",h""JII;,,,,...,,..,~., ... ",...1 m<J <I,'GpJf'lnI~

" •.-lIJII"n~n_.... loll" ... 1"""",10" 1,'''JIl''''"~''''.'1 Io<h

"",1.1<", II,1-><, ..lIm",m ,,' ",II \""'."',,..^~, ^101'1''''J,'",,, •

Itf" "n..~,r, I"I),n pr' , ••""" I,'rr.".... ,"'••""I l'n,l6r." )'''Un011 .. """ ,,'1M. '1", f"""",J.j'h,.1'1"".

n"",,.~, '"^Illl"I""'" I)." 1,,,.I'ljl",,",~.n~,'1m, ,.",1"""

n''') ,nII" ,I' <I,lnp n..-..1-><"",,,,, ,,"1.\, "',", ..\"i""""'""'"

..." ,",,,,,,1,'" 1'.01.

I'",,.j,,, ,,,,, '" I,,,..,,,o,.,,,..",~.",n^{J<O ...}In',"rr1,n"D<"

I"" _"I.", 10,,,,,,.>><,1,"

UnlJ"Ii"",11,.. I,t",.. k,,,,,,,"'" ,,11.nHr'rwno.h",1<Ii..

r"", ", ") """,In'"J" II., I," >"'""I, ..".,I<,,,.,,,r,,,, ...

r,,,I~,",.."""1','<''''~''''I ,,'~,_h,'" l"r"."",'"'' II,II~

~I'f.,(",I, I.1"1·,.·,,,,,1," ".'" ,,,,,1,,1.,"~,,,_" ",.;1'11 •• '"

:~.7.~,:~,~::;.·,,':~~:,:::~'~~,~~r~:::':,:,^I~::~.:~: :::~:;' ":i~ :~~,~;,~:~;'r-l 11",1.\010.\" .. "

ArlJrt"g:'lIIg~iI.lriinrr:lpl'0rll'ling

111,"'I' ,.,"IJG'".,'.",l""" .•^,1'Gt>«'rf""""'-' ....I~

"'''I'I'''''~'lll

H,--=_:'::_.-.- :~~.

, , , ,• 0

.

_,^,_..

---~~~~

")"-"'o{~

,, ,, , ,

..

^~

, ,

I

(8)

The publishing technique

The IBM CAP technique was chosen for the large number of documents that are to be produced using FRAME at ABB Data.

A-Gc0-~

LJ'~ _

^{. .}

• A table of contents and index can be created automatically. A page reference to every field description is automatically included in the index.

• Descriptions of integrations are indicated by a special symbol and a page reference is automatically included in the index.

8 Ulusu'ations are read by scanner, stored in a system library and included in the documents when required.

• Printouts from a 4250 laser printer are produced on a reel and forwarded to a pJinting house to be printed on quality paper.

There is also a need to combine parts from different system application manuals to produce tailor-made documentation for special reader categories. The YM/CMS environment provides a well known solution to the file handling requirements.

ABB Data possesses an advanced

knowledge of the IBM CAP technique from previous publishing projects.

CAP support for FRAME

• The FRAME layout is defined in the DCF/Script markup language.

The technical writer creates the text and places a mark in the text file where symbols (e.g. an ENTER key) is to be printed.

The page layout, page shifts, head- line fonts, etc., are controlled by DCF/Script (and by a special FRAME customization of DCF/

Script).

• Copies of screen contents and report examples can be u'ansferred from the application system to YM/

CMS and included in the step-by- step documentation of on-line dialogues. This applies to mainframe as well as PC applications.

• Field descriptions can be retrieved from a tem1 catalogue and then included in the documentation. Each field description is stored separately and can be included recurrently in the text. When a field description is changed, every occurence is thus updated.

Fiord dOlerlptlollll can bo rolrlovod frOIn • tarm call1ioguo

CeplD. 01 acroon layout.

tiro Included In tho dacumanl.

FRAME: A Concept for Documentation at ABB Data