documentation icon indicating copy to clipboard operation
documentation copied to clipboard

Tutorial housekeeping

Open javabster opened this issue 1 year ago • 7 comments

There are some small differences between all the existing tutorials that we should clean up.

All the tutorials currently on learning:

  • should use the same wording for each pattern step heading
  • should include a list of requirements at the start
  • should not include the author names at the top (there are some tutorials that were created from events that include the names)

This issue applies to both open and network tutorials

### Tasks
- [ ] https://github.com/Qiskit/documentation/pull/1379

javabster avatar May 02 '24 17:05 javabster

Related issue: #1189

abbycross avatar May 02 '24 19:05 abbycross

I wasnt able to find a single tutorial that does everything we want, but here are a couple that have good stuff:

  • For consistent subheading naming checkout this one: https://learning.quantum.ibm.com/tutorial/quantum-approximate-optimization-algorithm
  • for the requirements bullet list this PR: https://github.com/Qiskit/documentation/pull/1195/files

javabster avatar May 07 '24 14:05 javabster

The tutorials that should be reviewed as part of this PR:

  • [x] - https://learning.quantum.ibm.com/tutorial/variational-quantum-eigensolver
  • [ ] - https://learning.quantum.ibm.com/tutorial/quantum-approximate-optimization-algorithm
  • [x] - https://learning.quantum.ibm.com/tutorial/chsh-inequality
  • [ ] - https://learning.quantum.ibm.com/tutorial/max-cut
  • [ ] - https://learning.quantum.ibm.com/tutorial/heisenberg-chain
  • [x] - https://learning.quantum.ibm.com/tutorial/grovers-algorithm
  • [ ] - https://learning.quantum.ibm.com/tutorial/quantum-kernel-training
  • [ ] - https://learning.quantum.ibm.com/tutorial/submit-transpiled-circuits
  • [x] - https://learning.quantum.ibm.com/tutorial/repeat-until-success
  • [x] - https://learning.quantum.ibm.com/tutorial/build-repetition-codes

javabster avatar May 07 '24 14:05 javabster

another thing that would be good to add to each tutorial (but not sure how feasible it is) is an estimate of how much QPU time it takes. e.g. could this tutorial be run within the 10min open plan, or is it many hours so recommended to use serverless

javabster avatar May 07 '24 18:05 javabster

example notice: QPU time estimate: ~X QPU minutes on Y backend (NOTE: this is an estimate only, your runtimes may vary)

javabster avatar May 09 '24 14:05 javabster

@beckykd pointed out that the tutorials have a little clock icon and a time listed, which is the estimated time it takes to read that tutorial. When we start listing the QPU time too, it has the potential to be confusing, especially since the time-to-read is not labeled (only with the icon, and there's no hover text).

@javabster do we want both times listed on every tutorial? If so, we might want to get design help to make it clearer what the clock icon time means, so as not to confuse with the QPU time that we list in the tutorial itself.

abbycross avatar May 15 '24 19:05 abbycross

@abbycross noticed that we have a couple of tutorials that start with a small example, then "beef it up" to be utility-scale (or closer). Would that be a good pattern to follow everywhere? It might make open users able to run more of the tutorials.

beckykd avatar May 15 '24 19:05 beckykd

@abbycross and I landed on this text:

QPU time estimate: x minutes, y seconds on ibm_xyz. (NOTE: This is an estimate only. Your runtime may vary.)

beckykd avatar Jun 10 '24 15:06 beckykd

  • For consistent subheading naming checkout this one

Some notes on this text:

  1. There should not be periods in headings.
  2. "Primitives" in "Qiskit primitives" should be lower case.

beckykd avatar Jun 10 '24 17:06 beckykd

@abbycross and I landed on this text:

QPU time estimate: x minutes, y seconds on ibm_xyz. (NOTE: This is an estimate only. Your runtime may vary.)

Raul said that "Usage" would be a more accurate term than "QPU".

beckykd avatar Jun 11 '24 17:06 beckykd