Documentation Template

Exemplar 1: 1.3 Creating a Website

Exemplar 2: 2.2 Defining Tracks

DCMI/OCS Documentation Template

1.1 Procedure Title1

Brief text summary of procedure scope & objectives2

Responsible: Conf. Information Manager 3

Required: State any prerequisistes to completing the procedure, including data and/or files to be collected for uploading, images, approvals, etc. Anything the user must have before proceeding to complete the steps.4

  1. Process steps numbered, starting with definition of required preconditions – system states, prior procedures completed, user skills, user knowledge 5
  2. List includes 3-7 steps (5 +/- 2) 6
  3. Short, declarative statements of 1-2 actions per step 7
  4. Warning! Notes interspersed in steps and called out with special formatting highlight warnings of probable errors and/or guide user in recovering from probable errors8
  5. For users who need explanation about a step provide More detail . . . 9
  6. But AVOID Mr. Clipit-style intrusiveness – keep layered detail under user control!! 10

Notes Top

Flowchart: timeline or flowchart lists process milestone nodes – hover state for each node displays linked task list relevant there, color/icon-coded for participant role – some link returns linked list of all tasks by role – each task list link returns a 1-page procedure, as below; Farkas 1999, Barber 2003, Steehouder 2004; to support mental modeling of the overall task sequence – Manning 1998, Karreman & Steehouder 2004
[1] [numbered procedures to accomplish a task from the timeline, stated as a gerund; function is to help user determine if the current procedure is relevant to his/her immediate goals – Farkas 1999, van der Meij & Gellevij 2004]
[2] [function is to help user determine if the current procedure is relevant to his/her immediate goals – Manning 1998, Farkas 1999, Barber 2003; consider format of Rhetorical Structure Theory as statement of "relationship" between "nucleus" and "satellite," e.g., solution isSolutionFor problem -- Da Sliva & Henderson 2007]
[3] [state user role who completes task to help user determine if the current procedure is relevant to his/her immediate goals –Farkas 1999; match color/icon-coding of role indicators in flowchart]
[4] [van der Meij & Gellevij 2004, p. 7: Prerequisites are system states, user skills, user knowledge. Helps to state explicitly, especially starting screen.
[5] [van der Meij & Gellevij 2004]
[6] [van der Meij & Gellevij 2004]
[7] [per Streamlined Step Model of Farkas 1999; Delanghe 2000]
[8] [Farkas 1999, Delanghe 2000, van der Meij & Gellevij 2004, Steehouder 2004]
[9] [to "layer" detail relevant to user needs: Farkas 1999, Delanghe 2000, Eiriksdottir & Catrambone 2011]
[10] [Barber 2003]
[11] [state next step to be completed to support mental modeling of the overall task sequence – Manning 1998, Karreman & Steehouder 2004]