Hand­buch und Doku­men­ta­ti­on

Zeit: Don­ners­tag, 2. April 1998, 14.00 Uhr
Ort: HS 117
Mode­ra­ti­on: Frau Rich­te­rin am Amts­ge­richt Berg­mann
Refe­ren­ten: Herr Rich­ter am Ober­lan­des­ge­richt Beck­mann
Herr EDV-Sach­ver­stän­di­ger Brandt
Herr Wal­ker

Nach einer ein­lei­ten­den Erör­te­rung der von der neue­ren Recht­spre­chung auf­ge­stell­ten recht­li­chen Anfor­de­run­gen (Hei­ner Beck­mann, Rich­ter am OLG Hamm) sol­len aus sach­ver­stän­di­ger Sicht tech­ni­sche Kri­te­ri­en für Soft­ware­hand­bü­cher vor­ge­stellt wer­den (Jochen C. Brandt, EDV-Sach­ver­stän­di­ger, Brühl). Eine Dar­stel­lung kon­kre­ter Gestal­tungs­mög­lich­kei­ten am Bei­spiel des Hand­buchs für JURIS-Win­dows wird sich anschlie­ßen (Rein­hard Wal­ker, Abtei­lungs­lei­ter Doku­men­ta­ti­on und Pro­dukt­ent­wick­lung, JURIS-GmbH).Der Arbeits­kreis setzt die 1997 begon­ne­ne Erar­bei­tung der Anfor­de­run­gen an Benut­zer­do­ku­men­ta­tio­nen fort. In die­sem Jahr steht die Gestal­tung von Anwen­der­hand­bü­chern für Soft­ware­pro­gram­me im Vor­der­grund.

Ziel der dar­auf fol­gen­den Dis­kus­si­on im Arbeits­kreis ist es, einen Emp­feh­lungs­ka­ta­log zu ver­ab­schie­den, der Fir­men und Soft­ware­her­stel­lern als Richt­schnur die­nen kann.


PRÜFLISTE FÜR DIE GESTALTUNG VON ANWENDERDOKUMENTATION

1. Rich­tig­keit

1.1 Zuord­nung zum Pro­gramm (= Hand­buch-Iden­ti­fi­zie­rung):

  • Pro­gramm­be­zeich­nung
  • Pro­gramm-Iden­ti­fi­f­ak­ti­ons-Nr.
  • Pro­gramm-Ver­si­ons-Nr.
  • Pro­gramm-Frei­ga­be-Datum
  • ggfs. Lizenz-Nr., Ver­trags-Nr. etc.
  • Hand­buch-Ver­si­ons-Nr.
  • Hand­buch-Erstell-Datum
  • Hand­buch-Letz­tes-Ände­rungs­da­tum
  • Hand­buch-Ver­si­ons-Pro­to­koll (Chan­ge Log)

1.2 Pro­gramm­kon­for­me Dar­stel­lung

  • des Pro­gramm­auf­baus
  • der Pro­gramm­funk­tio­nen
  • der Mas­ken­fol­ge
  • der Ein­zel­mas­ken
  • der Mas­ken­funk­tio­nen, ‑teil­funk­tio­nen
  • der Feld­be­zeich­nun­gen
  • der mög­li­chen Feld­in­hal­te
  • der benutz­ba­ren Para­me­ter
  • der Lis­ten, Reports, Sta­tis­ti­ken etc.

1.3 fachliche/sachliche Rich­tig­keit

  • der Funk­tio­nen
  • der ver­wen­de­ten Grund­la­gen
  • der ein­ge­setz­ten Metho­den
  • von For­meln etc.

1.4 sprach­li­che Rich­tig­keit

  • Recht­schrei­bung
  • Gram­ma­tik
  • Aus­druck

2. Voll­stän­dig­keit

2.1 Instal­la­ti­ons­be­schrei­bung

  • Auf­lis­tung der gelie­fer­ten Unter­la­gen
  • Sys­tem­vor­aus­set­zun­gen (Hardware/Software)
  • tech­ni­sche Beschrei­bungs­merk­ma­le des Pro­gramms
  • Instal­la­ti­ons­pro­ze­dur
  • Stan­dard und Son­der­for­men
  • Erklä­rung der Instal­la­ti­ons-Para­me­ter, deren Zusäm­men­hän­ge
  • Typi­sche Sys­tem­ver­hal­tens­kenn­zah­len
  • Opti­mie­rungs­vor­schlä­ge
  • Benut­zer­spe­zi­fi­sche Anpas­sun­gen
  • Regis­tra­ti­ons- und Garan­tie­un­ter­la­gen

2.2 Beschrei­bung der Pro­gramm-Funk­tio­na­li­tä­ten

  • Sinn, Zweck, Auf­ga­ben­stel­lung und Ein­satz­ge­biet des Pro­gramms
  • Pro­gramm-Auf­bau
  • Haupt­funk­tio­nen des Pro­gramms
  • Menue-Struk­tur (Funk­ti­ons­ab­lauf)
  • Logi­scher Pro­gramm­ab­lauf zur jewei­li­gen (Einzel-)Aufgabe
  • Beschrei­bung der Ein­zel­funk­tio­nen
  • Zugrun­de­lie­gen­de Vor­schrif­ten
  • sons­ti­ge Grund­la­gen
  • Theo­re­ti­sche Grund­la­gen
  • Berech­nungs­me­tho­den
  • For­meln
  • Funk­tio­na­le Para­me­ter und deren Wir­kungs­wei­se
  • Ver­wen­de­te Nor­men und Nor­mie­run­gen (z.B. Ergo­no­mie, Tas­ten­be­le­gung (Short Keys), GUI = Gra­phi­cal User Inter­face = Stan­dard-Mas­ken-Lay­out)
  • Befehls-Kurz-Über­sicht (Refe­rence Card)
  • Mus­ter­an­wen­dun­gen
  • Tips und Tricks (Expert-Modus)

2.3 Beschrei­bung der Feh­ler­be­hand­lung

  • Lis­ten der Feh­ler­mel­dun­gen
  • Erläu­te­rung jeder ein­zel­nen Feh­ler­mel­dung
  • Hin­wei­se auf zu ergrei­fen­de Maß­nah­men
  • Hin­wei­se auf die Ver­mei­dung von Feh­lern

2.4 Daten­si­che­rung, ‑reor­ga­ni­sa­ti­on

  • Hin­wei­se: wann, wie oft, in wel­chem Umfang, mit wel­cher Metho­de, mit wel­chen Funk­tio­nen bzw. (spe­zi­el­len) Pro­gram­men etc.

2.5 Ver­hal­ten in Aus­nah­me­si­tua­tio­nen

  • Sys­tem­ab­bruch
  • Neu­start (Kalt‑, Warm­start)
  • Abwei­chun­gen zwi­schem erwar­te­tem und tat­säch­li­chem Ergeb­nis

2.6 Unter­stüt­zung durch den Pro­gramm­lie­fe­ran­ten/-her­stel­ler

  • Kon­takt­adres­se für den Benut­zer
  • Hot­line
  • Hel­pdesk
  • Schu­lung, Trai­ning, Benut­zer­fo­rum, Inter­net etc.
  • Garan­tie etc.

3. Über­sicht­lich­keit

3.1 Auf­bau und Glie­de­rung

(zum Gesamt­um­fang sie­he auch Kapi­tel Voll­stän­dig­keit)

  • Ein­füh­rung
  • Kurz­be­schrei­bung des Pro­gramms

- Auf­ga­be
– Auf­bau, Modu­le, Funk­tio­nen
– Zusam­men­hang der Modu­le
– Kurz­be­schrei­bung der Modu­le

  • Beschrei­bung je Modul

- Funk­tio­nen und deren Zusam­men­hang
– Arbeits­wei­se je Funk­ti­on /Teilfunktion

  • Bear­bei­tungs­hin­wei­se

- je Funk­ti­on, Teil­funk­ti­on, Mas­ke, Feld

  • Bear­bei­tungs­leit­fa­den je Auf­ga­be (Screen-Navi­ga­ti­on)
  • Ver­wei­se auf Mus­ter- und Bei­spiel­fäl­le
  • Son­der­fäl­le und Aus­nah­men
  • Auf­lis­tung von nicht-mach­ba­ren Auf­ga­ben
  • Anhang (tech­ni­sche Infor­ma­tio­nen, ver­wen­de­te Kon­ven­tio­nen, Nor­men etc.)

3.2 Ori­en­tie­rungs­hil­fen

  • Inhalts­ver­zeich­nis (ein­heit­lich und über­grei­fend)
  • Stich­wort­ver­zeich­nis:

- alpha­be­tisch
– funk­tio­nal geord­net
– Her­vor­he­bung von Basis­fund­stel­len
– Ver­weis auf Mus­ter­fäl­le/-bei­spie­le

  • Glos­sar (Ver­zeich­nis der Abkür­zun­gen und Fach­aus­dru­cke)
  • Quer­ver­wei­se im Text
  • Hin­wei­se im Text auf Nach­bar­the­men
  • sepa­ra­te Schnell-Infor­ma­ti­on = Befehls-Kurz-Über­sicht (Refe­rence Card)

3.3 For­mat, Form und Gestal­tung

  • Nor­ma­les Buch­for­mat (ca. 23 x 16 cm)
  • kein Foli­an­ten- oder Lexi­kon­for­mat
  • durch­ge­hen­de Sei­ten­nu­me­rie­rung
  • Regis­ter­ein­tei­lung (Griff- und/oder Farb­re­gis­ter)
  • hand­buch-ein­heit­li­che Sei­ten­auf­tei­lung

- Kapi­tel-/Ab­schnitts­hin­weis im Sei­ten­kopf
– gere­gel­te Schrift-Font-Ver­wen­dung
– Rand­be­mer­kun­gen
– Fuß­zei­len
– deut­lich erkenn­ba­re Quer­ver­wei­se

  • Ein­satz von Far­be als Orga­ni­sa­ti­ons­hil­fe

4. Ver­ständ­lich­keit

4.1 Fach­li­cher Inhalt des Pro­gramms

  • Qua­li­fi­ka­ti­on des Hand­buch­au­tors

- Sach­kennt­nis
– Erfah­rung
– Dar­stel­lungs­fä­hig­keit

4.2 Spra­che und Sprach­stil
  • Deutsch­sprach­lich (EG: jewei­lig gül­ti­ge Natio­nal­spra­che)
  • Satz­auf­bau, Wort­wahl etc.
  • ein­heit­lich durch­gän­gi­ge Begriff­lich­keit
  • Ver­mei­dung von Fremd­wör­tern bzw. sofor­ti­ge Erklä­rung oder Hin­weis auf Glos­sar
  • Ver­mei­dung von nicht­gän­gi­gen Abkür­zun­gen

4.3 Auf­be­rei­tung des fach­li­chen Inhal­tes

  • Kom­bi­na­ti­on von Text und Gra­fik
  • gra­fi­sche Dar­stel­lung für zeit­li­che und/oder sach­li­che Arbeits­se­quen­zen
  • Mas­ken­dar­stel­lun­gen in der Form, wie der Benut­zer sie tat­säch­lich auch sieht, auch far­big (Ima­go-Dar­stel­lung)
  • Mas­ken, Funk­tio­nen und Teil­funk­ti­on als gra­fi­sche Ein­zel­schritt­dar­stel­lung
  • Auf­ga­ben­be­zo­ge­ne Dar­stel­lung
  • Anwen­dungs­bei­spie­le

- Beschrei­bung des Bei­spiel-Sce­n­a­ri­os
– Aus­druck der Mas­ken je Ein­zel­schritt

4.4 For­ma­le Gestal­tungs­merk­ma­le

(sie­he auch Kap. Über­sicht­lich­keit)