How-to Guides Guidelines

1. Start explaining in one line what the user is going to learn

“This guide shows how to ….””

2. Focus on the actions

Don’t explain the concepts, only what actions have to be made and how they are made.

“If you want x, you have to do y.”

3. Provide options

Write a list of the different options before showing each one of them. Show the different ways in which you can perform the desired task.

4. Avoid explaining all the arguments/details from each option

Only mention the arguments that are needed to set the options apart. Link to the corresponding API reference page(s) for any further details.

5. Remember that how-to guides are task oriented, not Qiskit-oriented

If you are thinking about writing, for example, a “how to use (insert function)”, the place to do it is in that function’s API reference page

If there is only one function/method that enables the user to perform the task, give a very basic example and link to the corresponding API reference.

6. Use “you” instead of “we”.

“If you want x do y.”

“you can do z with a, b or c.””