Tutorials Guidelines

1. Get the user started

1.1 Lower the barrier of entry

Lower the barrier of entry as much as possible. Assume the user does not know much about what is covered in the tutorial. If we are expecting users to know something, make it explicit and link them to the needed explanations (See 6. Offer only minimum, necessary, explanation) Avoid jargon as much as possible. Provide a minimum necessary explanation when the jargon is introduced. (See 6. Offer only minimum, necessary, explanation)

1.2 Provide setup / prerequisites

1.3 Add sufficient comments to code

2. Provide a complete picture before they start

2.1 Provide overview at the start

Summarize what the tutorial is about in the first paragraph, ideally the first sentence

“In this tutorial, you will…”

2.2 Provide context

Add a context for why you want to do this tutorial? Or who is this tutorial for?

2.3 Summarize at the end

Summarize what the user has accomplished at the end of the tutorial

“You have built a secure, three-layer hylomorphic stasis engine…” Describe (and admire, in a mild way) what your learner has accomplished (note - not: “you have learned…”)

3. Ensure that the tutorial works reliably and repeatable

3.1 Test tutorials regularly

on supported platform and python / Qiskit versions (for example, via CI tests)

4. Ensure the user sees results immediately

4.1 Every step should produce a result

Every step the learner follows should produce a comprehensible result, however small. It can be a print statement showing a variable, a plot, etc.

“The output should look something like this…”

4.2 Each step should be brief

Ideally each step should not take longer than a minute. If it is longer than that, please consider ways to show intermediate results of the step, or at least make them aware that it takes a while, otherwise users will start worrying that something is going wrong.

5. Don’t try to teach

5.1 Provide concrete steps

Describe concrete steps, not abstract concepts, ignore options and alternatives.

5.2 Use titles or transition sentences to make steps more obvious

Titles for steps should be an action not a noun.

“First, do x. Now, do y. Now that you have done y, do z.”

5.3 Do not generalize

Focus on the particular instance of the case you want to demonstrate, do not generalize / provide abstractions.

6. Offer only minimum, necessary, explanation

6.1 Explain exactly what’s needed

Try to explain exactly what’s needed to get the steps done AND for the user understand everything they’re doing and why they are doing it in the first place. No more, no less.