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:
At the end of this tutorial, you should be able to:
- write a good tutorial
- review others' tutorials
- link(s) to other tutorials
Short theoretical primerLink
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"