Improve the most popular API references

[javabster]

(I suggest this issue be addressed in multiple PRs by the docs team)

We've gotten feedback that the API reference content could be better. This is also reflected in the data we collect on 👍 / 👎 , where the API reference consistently gets a worse ratio of negative to positive votes compared to the other docs. Specifically things like adding more code examples and return types could make this content better.

The following list includes (in order) the most visited API references (more than 200 views in the last 3 months). I recommend starting by going through this list in order, reviewing them and making any possible improvements.

• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.QuantumCircuit
• https://docs.quantum.ibm.com/api/qiskit
• https://docs.quantum.ibm.com/api/qiskit/circuit
• https://docs.quantum.ibm.com/api/qiskit/circuit_library
• https://docs.quantum.ibm.com/api/qiskit/transpiler
• https://docs.quantum.ibm.com/api/qiskit/qiskit.quantum_info.Statevector
• https://docs.quantum.ibm.com/api/qiskit/quantum_info
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.RZGate
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.CXGate
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.RYGate
• https://docs.quantum.ibm.com/api/qiskit/0.24/execute --> (it worries me how high on the list this page is...)
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.RXGate
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.Gate
• https://docs.quantum.ibm.com/api/qiskit/qiskit.quantum_info.SparsePauliOp (got more 👎 than 👍 )
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.CPhaseGate
• https://docs.quantum.ibm.com/api/qiskit/primitives
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.PhaseGate
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.CZGate
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.QFT
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.ZZFeatureMap
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.UGate
• https://docs.quantum.ibm.com/api/qiskit/visualization
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.XGate
• https://docs.quantum.ibm.com/api/qiskit/compiler
• https://docs.quantum.ibm.com/api/qiskit/qiskit.primitives.Sampler
• https://docs.quantum.ibm.com/api/qiskit/0.37/qiskit.providers.aer.AerSimulator (got more 👎 than 👍 )
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.ControlledGate
• https://docs.quantum.ibm.com/api/qiskit/qasm3
• https://docs.quantum.ibm.com/api/qiskit/qiskit.synthesis.SuzukiTrotter
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.iSwapGate
• https://docs.quantum.ibm.com/api/qiskit/qiskit.result.Result
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.RZZGate
• https://docs.quantum.ibm.com/api/qiskit/qiskit.quantum_info.Pauli
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.HGate
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.U3Gate
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.CCXGate
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.UnitaryGate
• https://docs.quantum.ibm.com/api/qiskit/0.43/qiskit.circuit.QuantumCircuit
• https://docs.quantum.ibm.com/api/qiskit/qiskit.quantum_info.Operator
• https://docs.quantum.ibm.com/api/qiskit/qiskit.quantum_info.Clifford
• https://docs.quantum.ibm.com/api/qiskit/qiskit.transpiler.CouplingMap
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.SwapGate
• https://docs.quantum.ibm.com/api/qiskit/qiskit.primitives.Estimator
• https://docs.quantum.ibm.com/api/qiskit/providers
• https://docs.quantum.ibm.com/api/qiskit/pulse
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.SGate
• https://docs.quantum.ibm.com/api/qiskit/circuit_classical
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.Initialize (got more 👎 than 👍 )
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.SXGate
• https://docs.quantum.ibm.com/api/qiskit/qiskit.visualization.plot_histogram
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.EfficientSU2
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.Parameter
• https://docs.quantum.ibm.com/api/qiskit/providers_fake_provider
• https://docs.quantum.ibm.com/api/qiskit/qiskit.visualization.plot_bloch_vector
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.TwoLocal
• https://docs.quantum.ibm.com/api/qiskit/qiskit.quantum_info.DensityMatrix
• https://docs.quantum.ibm.com/api/qiskit-ibm-runtime/qiskit_ibm_runtime.EstimatorV2
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.RXXGate
• https://docs.quantum.ibm.com/api/qiskit/qiskit.visualization.circuit_drawer
• https://docs.quantum.ibm.com/api/qiskit/qasm2
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.YGate
• https://docs.quantum.ibm.com/api/qiskit/qiskit.dagcircuit.DAGCircuit
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.ECRGate
• https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.Instruction

[jakelishman]

QuantumCircuit and qiskit.circuit recently got major overhauls - do you have any data on then pre- and post-, or should we count that as "we've looked at those two"?

[jakelishman]

Fwiw there's still probably plenty that can be done on those two, but if we're prioritising, it might make sense to pull up other things first.

[javabster]

yeah its quite a long list so i haven't looked through them yet to find specific improvements that could be made, if we think there are any that are already at their best we can just cross them off the list. also @abbycross and Becky might want to take a look through just for a copy edit even if theres no major updates to be made

[DisantHoridnt]

is this issue still available?

[jakelishman]

From #13297 (comment):

It'd be good to look at all off the gates in qiskit/circuit/library/standard_gates at the same time as each other, and to consider what information should be in there, and what should be in the corresponding QuantumCircuit method for those gates. It'd be good to keep that whole experience feeling fairly consistent, rather than some gates being updated and some not.

Fwiw, when we do get to that, it's probably good for a tech person and a docs person to work together on a single example gate as the first example, so we can align on everything, then the docs person can work on getting all the gates updated to the style. I have several technical concerns with the gates API pages (mostly concerning tensor-product notation which is at best highly confusing as written), and we'd want to have that agreed before somebody goes through all of the several pages.

[jakelishman]

@DisantHoridnt: this issue is primarily intended as tracking for the IBM Quantum documentation team, but if there's any subissues that might be helpful for an external contributor to look at, one of them might comment.

[DisantHoridnt]

got it, thanks for the reply