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 endusers 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 participation 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 positive.
"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 techni cal 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 de veloper and the end-user is thus often car ried out on the terms of the developer.
It is certainly no simple task for the sys tem developer to present the output of an analysis in a way that is easy to understand and relevant to the end-user.
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 organ izing a documentation project, structur ing the contents of a manual, editing texts, layout considerations, etc. 2 Technical support for producing docu mentation 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 applica tions, but is also intended to be used for writing pilot studies, system specifications, etc.
ABB Data offers its clients (the companies of the ABB Group) solutions to functionally oriented problems.
An end-user in one of the ABB compa nies 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.
When the decentralized organizational stmc ture 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 experi ence of the applications.
From this need of a total review of the existing documentation, the FRAME project emerged in May 1987.
As the name indicates, FRAME is mainly a tool, or frame, for presentation. FRAME can be regarded as a link between the devel opment 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
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 produc tion 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 develop ment project is to become successful.
The documentation project runs parallel to the system development process.
In a separate pilot study for the documenta tion 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. • Limits of the assignment. • Project plans..
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 docu mentation.
This is done in an over-view manner using written scenarios or case studies and in a detailed manner by describing functions in the end-user's business/production envi ronment 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 applica tions 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.
The documentation structure The structure of the documentation is de signed 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 sepa rate 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 under stand, and to gain efficiency in the docu mentation 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. (
SJ Ai, Xii, nil "ii, f)/t .111 filllll'J rtf A'~r."..."J." ,~:'~Dt ':';ii 'i!~ :{"~~!~(i~~ i!,)!" ,7,2 nOlO] 12.2 nO)l! Oil-line dia/oglles are described by mealls of step-by step examples, The screell colltellt is retrievdfrom the applicalioll system,
Orderllorplan • PM29 .--- --_. . _ - - "::"..:,I:.'"I:;.:..'."..::"_,:::.r:.:.m::m:r::".;"~::.,;~.::.:::1:":,:,,::l,II.:. .1:::.,',1~::":::.".:~");~m:.:'..::::":'.":~1..:::':~t.O':O-::.::,:,'I:I"..•w._:"'•".::l':~•:.."':~:~•.:-\..~.~.:::::.:.'.::J:"r..f.t:',::':".,.,J.=;-.,;:,".~,.~',:::,:.-:,•~:.~·::.'...v,::~::..,..,~~';..-..;:.:.,.~_·;..o:'.:.::.",.::=.,'...~, ::,I'!::"'".'-,.I........ -...,.::ri:n...'."..... 1".11... 11<,. ,,.j,. "..J r".t..,..I.'" ••,,, 1.... 11~ ,.,,~...~ ....ohl....." ..",.... '01" 1I~ r , 1""\ Ill... 11_;h l' =Y 1.1·"""ItI....""."."'·1,," .....'.. a~~ ,~: .~::..':';.::".,:.".. ,..-,~.. .:;:. ,,,r;:--,,,!,:.! "j'l""m"i,~mj"~,.¥,.":''?~.·.,,, ",.,.· ",.,.j,.i,"~..;,,, .","',"."! i! "",:, '::1-:::: ~:~:::::::;.;' :...... :r::=' "':",' " "":' :';1::::·~~~If:::~: :"" ":;;~:': "':' ":' :: .".w."".;:;";:;""."",;;;,.;.;.:;;;:,~o-_ _-"A",!,""O",ala -----~'"~o~.,"'c Reports are retrievedfrom list files 10 be illcll/ded ill the malll/al,
11110' n" fh "rr tit rU'I-(.. ,mu'.i. ""nm.1I '~';H l'I'~1 I r 1t,\N. "'h r",i"ll. ,!dr'''lt~' <il" .1,,,,"1, II" r A r."'t' t411'(.'" l"".'!(IO! IIDIIi."1 '·11 "II r""Fl'"
,~ 0 : " ' " IVII fllJTO: •• ""UII!'I"" H t~<{.}; •• 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 ,)() 1)<_"l'OI'" ,~.It"l'" '~"l"("I1.n}'lI'.I.) ~{'" 'f' '('{~ " . 'Olh'~ 0 ~;'ro . . . . ' ""·.~I·JV; ... 01.'01:......., III I.·.• , ~lt'" 11.11;: 'l'~ IlLl'JO~, rIlISt~l/'Il,I'"", 'I ". 1111: 1111: r'l_ >0;. . , ,,~. 'lI'l~IOI"'\IDI>~ rn.ll"I' .,!- ~'~11 '1 .......... '101 'Ill' .,u t ... ,~,,,, , .. ~ "I'll n.o", DI\".~'~.""t·M\·"'I~ '.110 H!'.· "III '!",\" 1,.",.','0· <If, oliO
l.'~·'" "11- ~"r"f' '''',''1°'''',0> FA.I..'I..N...A,.M".:""i, .... ~. '''' KUlIDtm ",ISV
' " t·0110
""""~~mm.' .11., m,., ,~'n~ ... m.. k"'ln,d,':ill. <nli" r l'Ok-r.. ",..1 ",,"n..h,I.~ tnl,tl I PoK'(",m,1 SuI>· ..::h ~nJr"lJl>·numm .. r"'dulll' .... r.-,. "pl'fi"·I,"i"1 II.;' .n,." I)~ h\-"',~!"",,, ... r.-" ,n I .",,1.. n.l"rr '''''''.'u' r--\ urf"I'.'~<1 I(.,>d roi, 1M",,' 1'1.1) In·Io'ul f,,, ~It «.1",,,_. f"I'IIft!· ADO O!!," .'====~~ "'lo.b •• '.!!~I~g 'l-~ ~h(,f-1->i-l-d- -.nOlO) -.-- --
kopanmodan ( CI704 ) ---- . _. --1.11. (I, ",.,Uri.ro.H . _ - - - - - . - -~ [ t,\I'1I4,1't" .... <1.1••.11...... "'''I" III~, u.",,,t, .,.. n",~
Il. n.,,, ~"r, h" ~,pd, ...... '" ,.,",,~ "",.,.... ~"I' Ir~UM~(-. Blll .11" r~. '" ...-~ IJ" 1 ... 1I~ 11't~1l1' , "' ••
II, ,.1':1>" u. <>I',~ . ".....,~'I". """ ."..... ulIt"II'"'' \'.1 .. "'"""n..." \'I~ .1110, .11" 1I.1t1o lo" ..>dIlIl"",.,..IIMII1It1 ....'".ri", 1'10,.,..,,,•.......,,..... , ... h_4 H'''....-.... l'''''' ~.l'''' '''_I. ---~-_. - - .- - - - - _ . L-[[(}-> ~~~ The arrows i"cdicate system integrations. There are rllltommic illdex references u? these symbols. \lariOlLS iUustratiolls are read by scallller to be ill M diu/ed in the documcllt(llioll. I
The IBM CAP technique was chosen for the large number of documents that are to be produced using FRAME at ABB Data.
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.
• 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 dia logues. This applies to mainframe as well as PC applications. • Field descriptions can be retrieved from a tem1 catalogue and then in cluded 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
A_-Gc0-~ L.J.'~ CeplD. 01 acroon layout. tiro Included In tho dacumanl. • A table of contents and index can be created automatically. A page refe rence 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 in cluded in the index. 8 Ulusu'ations are read by scanner, stored in a system library and in cluded 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.