Creating tutorials on OSBv1

We encourage users to turn their OSB projects into new tutorials.

An example tutorial repository can be found here. We refer to this example below.

First, open the model you wish to use for a tutorial. There are two main components to building a tutorial: configuring the default session, and writing the main step-by-step guide.

Configuring the default session

Any changes made to the state of a project, such as open widgets, re-coloring of populations, zoom or model position etc. can be saved and reused as the default working environment for the tutorial. For example, take a look at the Blue Brain Project Showcase session. Immediately you are greeted with three popup widgets, the model description, tutorial, and an info box. This is achieved simply by creating these windows in your original project (i.e. clicking “Model Description” and using the Console to add a popup widget, and then downloading the project using the button in the top-right toolbar.

The project.zip file contains an xmi file, a json file, a js file, and the results of any experiments you have run. Place the contents of the zip in a subdirectory of your repo. Then a link to the json file will appear on the models page of your project on OSB:

If you wish to include a step-by-step tutorial component, ensure that you have the tutorial widget open as part of the default session state: you can open a tutorial widget by pressing the book icon in the left toolbar.

Writing a step-by-step guide

The main component of tutorials are plain html files, one per step, and a json file to tie them together, see here for an example. To create interactive aspects, the quickExperiment javascript function can be used to add experiments with parameters set by the tutee, see here for an example. The json file should specify a name (tutorial title), default height and width of the tutorial widget, and a list of paths of the html files for each step, see here for an example.

Finally we need to add our tutorials to the tutorial widget by editing the json file downloaded in the step above (Configuring the default session). It may help to run this file through a formatter before editing. To the data field of the tutorial widget, add URLs pointing to the json file(s) that you created above (see here for an example). You may also wish to change the activeTutorial field under componentSpecific to the title of tutorial you wish to be initially displayed. Tutees may switch between tutorials using the book icon at the top-left corner of tutorial widget.

Existing tutorials

You can explore our existing tutorials here. The synaptic integration tutorial is still under development.

Support

Please get in contact at any stage of preparing your tutorial.