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 prob- lems. 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 documenta- tion projects using FRAME have been completed since then and still more will be com- pleted 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. • THE PROBLEM ( "This is how our new system will make your work easier." There are many tools and methods support- Intricate flow-charts and system configu- ing systems development, but how do you ration diagrams are readily included in end- present the result - the system and its advan- user documentation, with the intention of tages - to the end-users, reference-group clarifying matters, even though few end- members and company management? users are trained at interpreting the charts. Communication between the system de- When system documentation is produced, veloper and the end-user is thus often car- at all stages of the development process, ried out on the terms of the developer. much effort is by tradition concentrated on describing facts correctly and defining It is certainly no simple task for the sys- logical relationships in more or less techni- tem developer to present the output of an cal terms. analysis in a way that is easy to understand and relevant to the end-user. Elementary pedagogical considerations and presentation techniques are often neg- lected. 1 A SOLUTION ( ( FRAME is a concept for documentation deve)o)led by ADD Data. The FRAME concept consists of two main The goal for developing FRAME has parts: been to find a way in which to describe a system application from the end-user's point 1 Rules and recommendations for organ- of view. izing a documentation project, structur- ing the contents of a manual, editing FRAME is now used by ABB Data for texts, layout considerations, etc. producing manuals for end-user applica- tions, but is also intended to be used for 2 Technical support for producing docu- writing pilot studies, system specifications, mentation using IBM CAP technique in etc. a VM/CMS environment (DCF/Script and 4250, 3820 or 3812 laser printers). 2 ABB Data FRAME ABB Data offers its clients (the companies As the name indicates, FRAME is main- of the ABB Group) solutions to functionally ly a tool, or frame, for presentation. FRAME oriented problems. can be regarded as a link between the devel- opment environment and the end-user An end-user in one of the ABB compa- environment. nies is most often a user of several system applications, e.g. construction systems are The concept was developed by a project integrated with production- and purchasing group during 1987-88 and involved defining systems and the end-user functions can span the following items: over these system boundaries. • The activities of a documentation In many cases the end-user is not even project. aware of the fact that he/she is switching • The structure of a manual. between different applications when carry- e Text editing recommendations. ing out operations. • The documentation layout. • The publishing technique. New corporate organization • Organizing documentation main- When the decentralized organizational stmc- tenance. l ture of the ABB Group was implemented, • Introducing the documentation to the experienced central staffs of the parent the end-users. company no longer existed, and the staff functions were to be carried out by inde- Three application systems were used as pendent ABB companies. test cases - a purchasing system, a project administration system, and a system for This created a great need of better infor- quality control. mation concerning ABB Data systems to many new end-users with little or no experi- Every phase of the development process ence of the applications. was presented to the reference groups of the test projects for approval. From this need of a total review of the existing documentation, the FRAME project As a result of the FRAME project, ABB emerged in May 1987. Data has obtained a standard for end-user- oriented documentation, to be used through- out the system development process. 3 The technical writer At an early stage the FRAME project group found that producing documentation is a full time task for a specialist. In the production stage the writer describes The need for a technical writer function each function, chapter by chapter. has been recognized in industrial produc- tion for many years, but the same need is Describing functions as seen by the end- .not commonly acknowledged when devel- user is the foundation for FRAME docu- 'oping administrative system applications. mentation. ABB Data has now formed a special This is done in an over-view manner group of technical writers. The writers also using written scenarios or case studies and act as project leaders for the different in a detailed manner by describing functions documentation projects. in the end-user's business/production envi- ronment and relating the system to these The technical writer is as essential as the functions. programmer, the system analyst, the project leader and any other specialist if a develop- To accomplish this it is necessary to: ment project is to become successful. • Define the relevant functions. • Describe them in the correct step-by-step order. A documentation project • 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 The documentation project runs parallel that the texts can be easily understood by to the system development process. none-EDP-professionals and that the facts are correct. In a separate pilot study for the documenta- tion project, the following is defined: The introduction stage is just as impor- tant as the previous stages. For new applica- • Which functions that are to be tions the manual is distributed in connection described. This is thoroughly checked with the initial tTaining courses. For existing with a reference group of end-users. applications a special introduction meeting • Different reader categories; their is arranged for the end-users to get ac- characteristics (such as previous EDP- quainted with the manual. experience, general level of education, etc) and thus their documentation requirements. • Limits of the assignment. • Project plans.. 4 The documentation structure The documentation layout The structure of the documentation is de- A great deal of effort has been made to signed to make it possible to produce tailor- design a standardized layout in order to made manuals (across system boundaries) make the contents easy to read and to under- for different categories of end-users and to stand, and to gain efficiency in the docu- facilitate easy-to-understand explanations of mentation process. system integrations. Using FRAME, many initial problems Every function (as defined from the end- that arise when producing documentation user's point of view) is described in a sepa- have already been solved, and the writer can rate chapter. By combining selected chapters concentrate on creating the text. from different manuals, a category of read- ers can obtain a manual that is designed for The standardized layout also applies to their special requirements, 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. ( FunkUoner I kopanmodankon 7,2 12.2 Orderllorplan • PM29 nOlO] nO)l! SJ Ai, Xii, nil "ii, .111 filllll'J rtf A'~r."... "J." .--- --_. ._--- f)/t . "'" ~:: ~:'.~'::".~'\:::,"'.:~~ ,.. , ,:::. '" ,~:'~Dt ':';ii 'i!~ :{"~~!~(i~~ i!,)!" ,- .....".. ,.... :, ::;:: -.""~.,, 'I :r,: I :~~ I :~~:';~ ~v;:o.. .. ._.", •.. !., :m I 1;::1 : '~:J::::: ::: :~:: : l::::;:~, ~.= ..", ."" '" : :"'-......... -.... rn........ i ::~:l 1)::: I.. r;., ,... ,::::f=::~;: .....", ... _ II :; :::: ::.:: : ::-:r'J,-':'-;::' " ""1 ."" I'... .,..,·.,.·.. ..: :', I :: ::::, ::m ,w:t..-::.,~ :;.":":~;:-:"';.. .... u." .. ·~ ,m, ::::: ":: ::::: .... _.. '"'' :'."..... ::':~::. ,,, tOO •••• .. .. :'" 2~'~:..:";:~':;:' ':.'~' '" ,.,.. ,£" .•. LA ...... ,,,' •••••• f',~ ". , .. f1"~ 1.1" -.1 I .", ..... '0' "'~ 'l•• 1'_" ..·..", 1.>_ .",1 nil '" ~ "".1" ~"., rl . 1".11... 11<,. ,,.j,. ".. J r".t..,.. I.'" •• ,,, l~, .1",,, ",. it,,,",,, t: /0".." "..... r....."n....hn tf&t:~ ."",II~~".I"." ..,..."I"••""III,,,h'..'\url ~: "Hll . 1.... 11~ ,.,,~ . . . ~ .... ohl. ...." ..",.... '01" 1I~ r , 11_;h 1""\ Ill... l' =Y l:,~:'.~':;~ .. ::::..! ~..,;... u:c:~: ,,,".... ,. " I ..... .... ,....... ",......,. ....... n" ."' ,",' ""0-..... ",,.. , 1.1·"""ItI.... ""."."'·1,," .....'.. a~~ ~:~::s:\:-:.. . t~:::~ "'F::ilfi:ii! ~"'~":r:'~" ,~: .~::..':';.::".,:."..,..- ,~.. .:;:. ,,,r;:--- ,,,,. "'" "", ",...,"' .. ,,, ".. ",... '~ "., .", ,,,.,, "',"" !:! jlmi~mj~¥:?· ,,· ji~; .! i! , ..~ "",:, '::1-:::: ~:~:::::::;.;' :...... :r::=' "':",' " "":':';1::::·~~~If:::~: :"" ":;;~:': "':' ":' :: .."w."".;:;";:;""."",;;;,.;;:..;;;:,~o- _ _-"A",!,""O",ala -----~'"~o~.,"'c Oil-line dia/oglles are described by mealls ofstep-by- Reports are retrievedfrom list files 10 be illcll/ded ill step examples, The screell colltellt is retrievdfrom the malll/al, the applicalioll system, 5 Visa besfiillnlng 12.1 Manuel! faklurerlng PU51 11110' Fllllkllon~h('"'\krhnjug n" fh "rr tit rU'I-(.. ,mu'.i. ""nm.1I '~';H l'I'~1 I r 1t,\N. "'h r",i"ll. ,!dr'''lt~' 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 ,)() U" II, II..... r,·" ~'" t411'('" l"".'!(IO! IIDIIi."1 1)<_"l'OI'" ,~.It"l'" '~"l"("I1.n}'lI'.I.) .'1 ....... ,.Il~·.·r" 1)" .", .!IN '·11 "II ,~ r""Fl'" 0:"'" ~{'" 'f' 0 '('{~ ". 'Olh'~ ~;'ro ....' ""·.~I·JV; 01.'01:. ......, III ... '.110 H!'.· "III '!",\" oliO Il.,l.n I,,,. ,-" I.·.•, ~lt'" 11.11;: 'l'~ 1,.",.','0· 0;...., ,,~. rn.ll"I' 'lI'l~IOI"'\IDI>~ I~, I." .,'1 •• \o,... lh ... h .Il" ,,,h.,,,I, HI' .i ••" '",,' ~I.I. ,M .,!- ~ , .. "I'll '1 .......... '101 'Ill' .,u t ... ~'~11 n.o", DI\".~'~.""t·M\·"'I~ ,~,,,, "11- ~"r"f' '''',''1°'''',0> .',I''''''rr I.,,,N' I' .. I,,, I "n.l"w,~ lie., M, ,,, II ." ~¥, I. [:~',:::':~;>~~';,:;;,'~,;;~';."'rr...'" _I '" I ,.. ,t .. " .. J, •• " 'MI'''''' '"">tll'rr' /i,"" U r1 ~".l· ..::h ~nJr"lJl>·numm .. '" t·0110 r"'dulll' .... r.-,. "pl'fi"·I,"i"1 II.;' .n,." I)~ h\-"',~!"",,, ... r.-" ,n I .",,1.. OElOPP n.l"rr ( OELISLUlnJU· I(.,>d roi, 1M",,' 1'1.1) In·Io'ul f,,, ~It «.1",,,_. f"I'IIft!· LAGO '''''''.'u' r--\ urf"I'.'~<1 ADO O!!,".'- ====~~ /lBB 0'11<1 "'lo.b •• '.!!~I~g 'l-~ PLUTO Simplifiedflow-c1wrls show the recol/ullellded Stalldardized descriptiolls offields alld screell working order. lOyD Ills. 8.1 Reglstrera besllillnlng Lonerapporlering 9.1 - - - -.- -.- - - ---. _. --- nOlO) kopanmodan ( CI704 ) nDlI) ~h(,f1>ild ArlJrt"g:'lIIg ~iI.l riinrr:lpl'0rll'ling 111, "'I' ,., "IJ G'" .,'.",l""" .• ,1 'Gt>«'rf""""'-' .... I~ [t Il. n.,,, ~"r, h" ~,pd, ...... '" ,.,",,~ "",.,.... ~"I' Ir~UM~(-. Blll .11" "'''I'I'''''~'lll r~. '" ...-~ IJ" 1 ... 1I~ 11't~1l1' , "'•• \'14 '" II, ,.1':1>" u. <>I',~ .".....,~'I". """ ."..... u lIt"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 H,--=_:'::_.-.- : ,, . 1.11. (I, ",.,Uri.ro.H H'''....-.... l'''''' ~.l'''' '''_I. ._--- - -.- - -- .- - -- --_.- , ,, -~ ---~-_. • 0 ,. ---------------~~~~ foil. 1"1''''''''"''.'' '.." ... ,.n '",." ".",.,1 ....,.,,,, "'" d••", .. f;',~::'~~," ';\';l ;;;:~I'l ,~,.~~: '~~r:;' "Il,l1a:Oj' ,:;.::,~;:',~ ~;~';. :.' ~·~,,'~:~Ij,_ L-[[(}-> II" I,,, "I""'" ,on 11" ~~~ "" "• I"", "n", h""JII;,,,,... .-lIJII"n~n_ .... loll" ... 1"""",10" ,,..,~. , ... ",.....1 m<, .. lIm",m ,,' ",II \""'."',,.. ~, 101'1'''' J,'",,, • [rJQ.~~> Itf" "n.. ~, r, I" I),n pr' , ••""" I,'rr.".... ,"'••"" I )'''Un 011 ..""" ,,'1M. '1", f"""",J.j' h,. 1'1"". I l'n, l6r." n"",,.~, '" Illl "I""'" I)." 1,,,.I'ljl ",,",~.n~, '1m, ,.",1""" [~~:.:> ....." n''') ,n II" ,I' <"",,,,, ,," 1.\, "',", .. \"i""""'""'" ,",,,,,,1,'" 1'.01. I'" ,,.j,,, ,,,,, '" I,,,.. ,,,o,.,,,.. ",~. ",n J><,1," UnlJ" Ii"", 11,.. I,t",.. k,,,,,,,"'" ,,11.n Hr'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 •• '" ,,, ,,, .. ")"-"'o{~ :~.7.~,:~,~::;.·,,':~~:,:::~'~~,~~r~:::':,:, I ~::~.:~: :::~:;' ":i~ :~~,~;,~:~;' r-l 11",1.\010.\" .. " ,, ~ P"O"'I.O;;"---------A~B'!'rt.n-'-'-.--. --L~""'I rM,,'ng ,,' The arrows i"cdicate system integrations. There are \lariOlLS iUustratiolls are read by scallller to be ill M rllltommic illdex references u? these symbols. diu/ed in the documcllt(llioll. 6 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. Fiord dOlerlptlollll can CeplD. 01 acroon layout. There is also a need to combine parts bo rolrlovod frOIn • tiro Included In tho _ tarm call1ioguo dacumanl. from different system application manuals to produce tailor-made documentation for special reader categories. The YM/CMS A-Gc0-~ LJ'~ . . 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 • A table of contents and index can be DCF/Script markup language. created automatically. A page refe- The technical writer creates the text rence to every field description is and places a mark in the text file automatically included in the index. where symbols (e.g. an ENTER key) • Descriptions of integrations are is to be printed. indicated by a special symbol and a The page layout, page shifts, head- page reference is automatically in- line fonts, etc., are controlled by cluded in the index. DCF/Script (and by a special 8 Ulusu'ations are read by scanner, FRAME customization of DCF/ stored in a system library and in- Script). cluded in the documents when • Copies of screen contents and required. report examples can be u'ansferred • Printouts from a 4250 laser printer from the application system to YM/ are produced on a reel and forwarded CMS and included in the step-by- to a pJinting house to be printed on step documentation of on-line dia- quality paper. 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. 7