GUIDELINES.md

Guidelines for writing tutorials

First read the overall project contributing guidelines. These are all included in the qiskit documentation:

https://qiskit.org/documentation/contributing_to_qiskit.html

Introduction

The main goal of qiskit-experiment tutorials is to serve as user guides for the various package components such as the characterization and calibration experiments. To this end each tutorial should cover the main (if not all) use-cases of the documented functionality, including code examples and expected outputs. Another objective of the tutorials is to provide the user with basic background on each experiment method. Hence a good practice would be to have in the beginning of the tutorial a short background explanation, preferably 1 or 2 paragraphs long which includes the main literature references as well as a link to the relevant chapter in the Qiskit textbook, if available. See for example the Randomized Benchmarking tutorial.

Below are more concrete guidelines pertaining to various tutorial aspects:

Formatting guidelines

• For experiments, tutorial title should be just the name of the experiment. Use regular capitalization.
• For sub titles of how-to steps - use present progressive. E.e. "Saving exp data to the DB" (instead of "Save exp data to the DB")
• Use math notation as much as possible (e.g. use $\frac{\pi}{2}$ instead of pi-half or pi/2)
• Use headers, subheaders, subsubheaders etc. for hierarchical text organization. No need to number the headers
• Use device names as shown in the IBM Quantum Services dashboard, e.g. ibmq_armonk instead of IBMQ Armonk
• put identifier names (e.g. osc_freq) in code blocks using backticks, i.e. osc_freq

Content guidelines

• First section should be a general explanation on the topic. Put 2-3 most relevant references (papers and Qiskit textbook)
• Cover the common use-cases of the documented functionality (e.g. experiment)
• For each use-case, provide an example output, such as console printings and plot figures
• Cover all the required and common params (e.g. experiment and analysis options)
• For an experiment tutorial, cover using the experiment in a composite experiment setting