Skip to content

How to make a good romi tutorial ?Link

  • Format: starts with "How", is a question, should be focused to a user-oriented question
  • content: try to build a streamline procedure. If the procedure is too complicated (like different case scenarios, if you need to explain 'if you want to ... and/or if you want to...'), consider splitting your tutorial in as many tutorials as needed to obtain a streamline procedure.

Here a suggested sections for our romi tutorials:

ObjectivesLink

At the end of this tutorial, you should be able to:

  • write a good tutorial
  • review others' tutorials

PrerequisiteLink

  • Installations
  • link(s) to other tutorials

Short theoretical primerLink

(if needed)

Step-by-step tutorialLink

1. This is step 1Link

For non-computer experts, please remember to provide detailed information each time a command line is needed:

  • explain if a new terminal should be open or not ;
  • precise from where the command(s) should be executed ;
  • indicate whether a particular isolated environment should be activated (e.g. conda environment) ;
  • give precise and detailed command lines needed (make sure that all commands are given)
cd my repo  #precise from where the command should be executed
command 1  #code comments are welcome !
command 2  # this is for....

Provide ideas of the expected results to check that the commands were successfully run. examples:

a new folder/object is created

the terminal says "useful information"

2. This is step 2Link