Changes between Version 25 and Version 26 of GeniExperiments


Ignore:
Timestamp:
03/25/13 14:49:00 (11 years ago)
Author:
hmussman@bbn.com
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GeniExperiments

    v25 v26  
    6565 
    6666
    67 == 5)  Basic GENI Experiment/Tutorial/Test Workflow (Harry) ==
     67== 4)  Basic GENI Experiment/Tutorial/Test Workflow (Harry) ==
    6868
    6969Start with one "Basic GENI Experiment/Tutorial/Test Workflow", and later introduce variations that cover additional types of experiments
    7070
    71 === 5.1)  Uses ===
     71=== 4.1)  Uses ===
    7272
    7373Use to guide:
     
    8181d)  Operational tests, i.e., acceptance tests of GENI racks
    8282
    83 === 5.2)  Graphical view of steps ===
     83=== 4.2)  Graphical View of Steps ===
    8484
    8585[http://groups.geni.net/syseng/attachment/wiki/ExperimentMgmt/ExpLifecycle-8step.jpg  figure] 
    8686
    87 === 5.3)  Detailed steps ===
     87=== 4.3)  Detailed Steps ===
    8888
    8989[http://groups.geni.net/geni/wiki/TestTutorialExperimentWorkflow  basic workflow steps]
    9090
    91 === 5.4)  Summary of steps ===
     91=== 4.4)  Summary of Steps ===
    9292
    9393a)  Includes eight steps that are self-contained, which allows for all the variations in flow that occur in a real experiment:  repeating steps (e.g., many runs);  re-ordering steps (e.g., analyzing much later);  skipping steps  (e.g., do not archive)
     
    121121 + References
    122122 
    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
     130A 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
     134a)  Start with a static document.
     135
     136b)  Typically provide as a web page, with an option to print it out
     137
     138c)  Two "best-in-class" examples were found:
    137139
    138140 + Web page [http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html  Getting Started with Amazon EC2 Linux Instances]
     
    142144 + Configuration manuals from Cisco, such as [http://groups.geni.net/geni/attachment/wiki/GeniExperiments/cisco%203750%20%20smart_install.pdf    Cisco Smart Install Configuration Guide]
    143145
    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:
     146d)  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
     148e)  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
     150f)  Each step should be phrased:  "do this..";  consider a controlled vocabulary, such as:  use;  do;  repeat;  stop;  load;  execute;  see;  expect
     151
     152g)  Each step should be indented, so that the user can check off the steps on the left, when the web page is printed.
     153
     154h)  Additional notes can be included, with a different indentation than the steps, to provide notes to the user
     155
     156i)  Notes to the user may include:  tips;  cautions;  FAQs;  troubleshooting info;  references
     157
     158j)  The configuration in a step should typically include a figure
     159
     160k)  When a selection or command entry is required, a box should be used to show the command line, GUI entry and/or script
     161
     162l)  When a selection is required by the user, it should be clear what they are to enter
     163
     164m)  Expected results should be presented, typically with a box that shows a command line, GUI entry, script, table or graph
     165
     166n)  Formatting conventions should be used to aid understanding:
    165167
    166168 +  See pvii of [[http://groups.geni.net/geni/attachment/wiki/GeniExperiments/cisco%203750%20%20smart_install.pdf    Cisco Smart Install Configuration Guide]   for conventions in Cisco example
     
    170172 +  But, the overall look should not be too "busy"
    171173
    172  o)  Suggested formatting conventions are:
     174o)  Suggested formatting conventions are:
    173175
    174176 + TBD
    175177
    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
     180a)  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
     192b)  Then, this reference page provides an "experiment description" for a particular experiment run
     193
     194c)  Of course, the backup option is to print the static web page, and then write on it
     195
     196d)  The user's entries may include:
    183197
    184198 + check-offs for each step
     
    190204 + notes made
    191205
    192  
     206=== 5.3)  Additional One-Page Summary Document ===
     207
     208a)  To supplement a document on a web page, particularly for an in-person tutorial, provide a one-page summary, that includes specific information for this user (i.e., their assigned credentials), and allows them to easily check off steps, and capture simple notes and results.
     209
     210=== 5.4)  Additional Video "Document"  ===
     211
     212
     213
    193214
    194215== 8)  Example Tutorials (Jeanne and Harry) ==