By Gloria Amos
When the Code Works but the Documentation Falls Short
Quantum Software Development Kits (SDKs), such as IBM’s Qiskit, Google Cirq, and PennyLane, provide developers with the tools to build, simulate, and execute quantum programs. However, having functional software does not guarantee that its capabilities are clearly communicated. Well-written documentation is an integral part of making quantum technology accessible to both developers and researchers. A 2025 exploratory study involving 251 quantum programming practitioners found that 60.6% learn quantum languages from official documentation, citing inadequate or incorrect documentation and usage examples as significant challenges. Furthermore, the Unitary Foundation’s 2025 Quantum Open Source Software Survey revealed that project documentation and source code ranked above chatbots as primary information sources for developers. This highlights the critical importance of clear documentation and understandable code in quantum software development.
As efforts to lower the barriers to entry for quantum computing increase, providing simplified, easily understandable documentation is essential. While quantum programming cannot eliminate the need to understand complex quantum concepts, SDK maintainers can reduce unnecessary ambiguity in how these concepts are exposed through software. My experience contributing to Qiskit offers a practical example of how improving documentation accuracy and implementing appropriate testing can make existing quantum functionalities more accessible.
A Quantum SDK provides an integrated collection of APIs, compilers, transpilers, simulators, libraries, and interfaces that help developers optimize, execute, and debug quantum algorithms. IBM Quantum defines the Qiskit SDK as an open-source tool for working with quantum computers at the level of extended (static, dynamic, and scheduled) quantum circuits, operators, and primitives. Consequently, making quantum SDKs more accessible involves various efforts to make these powerful tools more readily available to the community.
Where Quantum SDKs Create Developer Friction
A recent paper, A Taxonomy of Real Faults for Hybrid Quantum-Classical Software Architectures by Avner Bensoussan et al., notes that online quantum documentation does not always reflect the latest API versions. As a result, programs have a short life expectancy, forcing developers to constantly adapt their code to newer versions.
Because quantum computing is often seen as abstract and confusing, ambiguous or outdated documentation creates significant friction in the developer experience. Quantum operations, qubit ordering, measurements, and mathematical representations require specialized knowledge that conventional software developers may lack. Incomplete API descriptions, omitted edge cases in examples, and discrepancies between documented parameters and actual functionalities introduce avoidable confusion. Therefore, well-written documentation must explain concepts clearly using foundational terms. Accurate explanations, practical examples, and understandable APIs effectively reduce the barriers to entry.
What a Qiskit Contribution Revealed
As a junior developer without a STEM background or a physics undergraduate degree, I became curious about quantum computing and its potential to solve problems beyond the reach of classical computers. I began exploring quantum information and looked for beginner-friendly issues in the Qiskit SDK to contribute to. Contributing to open-source projects is widely recognized as an excellent way to connect with industry experts, gain experience, and strengthen technical skills. During this process, I found a reopened issue regarding confusing API References documentation, which had originally been opened by a quantum software engineering researcher.
The Issue
Upon investigating the issue, I confirmed inconsistencies between the implemented functionalities and the explanations provided to developers. For example, the PolynomialPauliRotationsGate covers “X”, “Y”, and “Z” bases, but the documentation only mentioned the default “Y” basis. Additionally, the most and least significant qubits were not clearly defined. There was also a typo in the mapping for the HalfAdderGate. Together, these inconsistencies caused avoidable misunderstandings for both developers and researchers. After investigating these issues, I used the official Qiskit documentation as a guide to make several changes to add concise mappings, correct wording, and added “X” and “Z” basis test coverage.
The Role of Testing
After a careful review of my initial pull request, repository maintainers notified me that there was no test coverage for the newly added bases. I subsequently added test coverage for the “X” and “Z” basis cases in test_functional_pauli_rotations.py. Because I was working through a browser editor and could not run the test suite locally, the maintainers manually checked and confirmed the tests were correct. This experience taught me that testing is crucial for software reliability, as it verifies that the implementation behaves as expected and aligns with the documentation. Ultimately, my pull request passed 27 checks, was backported, and merged successfully.
Conclusion
Contributing to Qiskit demonstrated that improving quantum software goes beyond introducing new features and tools. It also involves making existing tools easier to understand and ensuring that functionalities, tests, and documentation are perfectly aligned. My contribution highlighted how clearly written documentation, thorough testing, and open-source collaboration work together to elevate software quality. While these practices cannot remove the inherent complexities of quantum computing, they successfully eliminate avoidable confusion from the developer experience. Ultimately, the usefulness of a Quantum SDK depends not only on its technical capabilities but also on how easily developers can understand and apply it for the greater good.
Gloria Amos is a software developer.