123 | | == 6) Current Mapping from Basic GENI Experiment/Tutorial Workflow Steps to Experiment Management Tools (Jeanne) == |
124 | | |
125 | | [http://groups.geni.net/syseng/attachment/wiki/ExperimentMgmt/ToolBreakdownTable.jpg figure] |
126 | | |
127 | | |
128 | | == 7) A Standardized GENI Experiment/Tutorial Format, Optimized for Ease of Use (Jeanne and Harry) == |
129 | | |
130 | | a) A standardized format, optimized for easy understanding, will make it is easier for the user to understand a tutorial, particularly after completing another GENI tutorial |
131 | | |
132 | | b) Start with a static document, that indicates how user can modify for their own experiment |
133 | | |
134 | | c) Typically provide as a web page, with an option to print it out |
135 | | |
136 | | d) Two "best-in-class" examples were found: |
| 123 | === 4.5) Mapping from Steps to Experiment Management Tools (Jeanne) === |
| 124 | |
| 125 | [http://groups.geni.net/syseng/attachment/wiki/ExperimentMgmt/ToolBreakdownTable.jpg figure] |
| 126 | |
| 127 | |
| 128 | == 5) A Standardized GENI Experiment/Tutorial Format, Optimized for Ease of Use (Jeanne and Harry) == |
| 129 | |
| 130 | A standardized format, optimized for easy understanding, will make it is easier for the user to understand a tutorial, particularly after completing another GENI tutorial |
| 131 | |
| 132 | === 5.1) Standardized Document === |
| 133 | |
| 134 | a) Start with a static document. |
| 135 | |
| 136 | b) Typically provide as a web page, with an option to print it out |
| 137 | |
| 138 | c) Two "best-in-class" examples were found: |
144 | | e) Include a "navigation feature", to find the individual steps; in the Amazon case, this is done with a table, that includes links to each step. |
145 | | |
146 | | f) Number the steps for easy reference; follow the approach in the Amazon table: steps 1 - n; within a step, sub-steps 1 - n; optionally, within a sub-step, sub-sub-steps a - z |
147 | | |
148 | | g) Each step should be phrased: "do this.."; consider a controlled vocabulary, such as: use; do; repeat; stop; load; execute; see; expect |
149 | | |
150 | | h) Each step should be indented, so that the user can check off the steps on the left, when the web page is printed. |
151 | | |
152 | | i) Additional notes can be included, with a different indentation than the steps, to provide notes to the user |
153 | | |
154 | | j) Notes to the user may include: tips; cautions; FAQs; troubleshooting info; references |
155 | | |
156 | | j) The configuration in a step should typically include a figure |
157 | | |
158 | | k) When a selection or command entry is required, a box should be used to show the command line, GUI entry and/or script |
159 | | |
160 | | l) When a selection is required by the user, it should be clear what they are to enter |
161 | | |
162 | | m) Expected results should be presented, typically with a box that shows a command line, GUI entry, script, table or graph |
163 | | |
164 | | n) Formatting conventions should be used to aid understanding: |
| 146 | d) Include a "navigation feature", to find the individual steps; in the Amazon case, this is done with a table, that includes links to each step. |
| 147 | |
| 148 | e) Number the steps for easy reference; follow the approach in the Amazon table: steps 1 - n; within a step, sub-steps 1 - n; optionally, within a sub-step, sub-sub-steps a - z |
| 149 | |
| 150 | f) Each step should be phrased: "do this.."; consider a controlled vocabulary, such as: use; do; repeat; stop; load; execute; see; expect |
| 151 | |
| 152 | g) Each step should be indented, so that the user can check off the steps on the left, when the web page is printed. |
| 153 | |
| 154 | h) Additional notes can be included, with a different indentation than the steps, to provide notes to the user |
| 155 | |
| 156 | i) Notes to the user may include: tips; cautions; FAQs; troubleshooting info; references |
| 157 | |
| 158 | j) The configuration in a step should typically include a figure |
| 159 | |
| 160 | k) When a selection or command entry is required, a box should be used to show the command line, GUI entry and/or script |
| 161 | |
| 162 | l) When a selection is required by the user, it should be clear what they are to enter |
| 163 | |
| 164 | m) Expected results should be presented, typically with a box that shows a command line, GUI entry, script, table or graph |
| 165 | |
| 166 | n) Formatting conventions should be used to aid understanding: |
176 | | p) Option: utilize a production method for the web page, so that the user can copy the page as a template, include entries for this particular run, and store everything for later reference; |
177 | | |
178 | | + Then, this reference page provides an "experiment description" for a particular experiment run |
179 | | |
180 | | + Of course, the backup option is to print the static web page, and then write on it |
181 | | |
182 | | q) The user's entries may include: |
| 178 | === 5.2) Customized Document, Optionally Including Annotations and/or Results |
| 179 | |
| 180 | a) Utilize a production method for the web page, so that the user can: |
| 181 | |
| 182 | + copy the page as a template, |
| 183 | |
| 184 | + include entries for this particular run, |
| 185 | |
| 186 | + add annotations |
| 187 | |
| 188 | + include results |
| 189 | |
| 190 | + and store everything for later reference; |
| 191 | |
| 192 | b) Then, this reference page provides an "experiment description" for a particular experiment run |
| 193 | |
| 194 | c) Of course, the backup option is to print the static web page, and then write on it |
| 195 | |
| 196 | d) The user's entries may include: |