A student here is working with some colleagues to add "tutorials" - which would include UI highlighting (e.g., "switch to the measure tool") and interactive questions.

I'd like some feedback in terms of syntax and the kinds of questions.

  • A panel shows what to do.
  • An orange outline points at the button or menu to use. (Color ideas?)
  • Each step moves on once the student has done it: picked the right tool, built the right molecule, run Optimize Geometry, or typed in a correct measurement.

A tutorial is a Markdown file

  • # is the tutorial's title, and the paragraph after it is a short description.
  • Each ## heading starts a step. Its text is what the student reads.
  • A step can include a small do block that says what the student should do. The outline then points at each thing in turn, and the step checks itself.

Here is a complete, short tutorial:

# Bond Angles and Lone PairsBuild ammonia and see how a lone pair squeezes the bond angle.## Build ammoniaStart a new molecule, pick the {tool:draw}, choose **Nitrogen**, and clickonce in the 3D view. Avogadro adds the hydrogens for you.```donewtool drawelement Nset adjust-hydrogens onbuild NH3 | Click once on an empty spot if H2O: That's water. Press {key:Undo}, choose Nitrogen (7), and click again. if 2 NH3: You've made two ammonia molecules. Press {key:Undo} to undo one.```## Clean up the shapeChoose {menu:optimize}. Avogadro uses a force field to find a sensible shape.```dooptimize```## Measure the H–N–H anglePick the {tool:measure}, then click H, N, H **in that order**. The middle atomis the corner of the angle. Type the angle you see in the box below.```dotool measuremeasure angle H-N-H expect 100..108 record "Ammonia: H–N–H angle"after: Ammonia's lone pair takes up more room than a bond, so the angle is a little smaller than a perfect tetrahedron (109.5°).```## Your resultsClick **Copy results** to paste your measurements into your lab report.```doresults```

That's the whole format. Anything outside a do block is ordinary Markdown, including bold, lists, tables, links and images. (Things like and are available, though I'm still thinking about full MathJax / LaTeX formulas.)



Discuss this on our forum.