Documentation and Community Guidelines: Building Inclusive and Usable Quantum Projects

Table of Contents

1. Introduction
2. Why Documentation Matters in Quantum Software
3. Types of Documentation in Quantum Projects
4. Getting Started Guides and Quickstarts
5. API Documentation and Autogenerated References
6. Tutorials and Example Notebooks
7. Inline Comments and Developer Notes
8. User-Centric vs Research-Centric Docs
9. Tools for Writing and Hosting Documentation
10. Writing Style for Quantum Docs
11. Markdown, reStructuredText, and Jupyter Docs
12. Keeping Docs Up to Date
13. Establishing Contribution Guidelines
14. Community Code of Conduct
15. Issue and PR Templates
16. Supporting New Contributors
17. Building Inclusive Communities
18. Moderation and Review Etiquette
19. Encouraging Feedback and External Resources
20. Conclusion

1. Introduction

Good documentation and clear community guidelines are foundational to maintaining a sustainable, inclusive, and collaborative open-source quantum software ecosystem.

2. Why Documentation Matters in Quantum Software

• Lowers the barrier to entry for new contributors
• Helps non-physicists participate in quantum computing
• Increases adoption and retention of users and collaborators

3. Types of Documentation in Quantum Projects

• End-user documentation
• Contributor/developer documentation
• API references
• Scientific rationale and design docs

4. Getting Started Guides and Quickstarts

Provide clear, minimal reproducible paths to:

• Install dependencies
• Run a sample quantum circuit
• Understand project structure

5. API Documentation and Autogenerated References

Use tools like:

• Sphinx (with autodoc)
• MkDocs
• Docstrings in PEP257 or Google format

6. Tutorials and Example Notebooks

• Real-world examples (VQE, QAOA, teleportation)
• Notebooks that explain code and theory
• Output cells pre-run to aid discovery

7. Inline Comments and Developer Notes

• Explain intent, not just implementation
• Use docstrings to describe qubit layout, params
• Mark TODOs and FIXMEs with clear rationale

8. User-Centric vs Research-Centric Docs

Balance:

• Practical instructions for developers
• Mathematical background for researchers

9. Tools for Writing and Hosting Documentation

• Read the Docs
• GitHub Pages
• JupyterBook for interactive docs

10. Writing Style for Quantum Docs

• Keep tone concise and accessible
• Use consistent quantum terminology
• Avoid over-assuming physics background

11. Markdown, reStructuredText, and Jupyter Docs

• Markdown: general documentation
• rST: Sphinx projects
• Jupyter: tutorials and dynamic walkthroughs

12. Keeping Docs Up to Date

• Use CI to check doc builds
• Link docs to code versions via tags/branches
• Encourage doc PRs with feature PRs

13. Establishing Contribution Guidelines

Include:

• Forking and branching policy
• Code style guides
• How to write and run tests

14. Community Code of Conduct

• Set expectations for respectful interactions
• Define unacceptable behaviors and enforcement process
• Use Contributor Covenant template or adapt

15. Issue and PR Templates

• Help guide contributor submissions
• Ask for reproducibility steps
• Encourage minimal working examples (MWEs)

16. Supporting New Contributors

• Tag beginner issues
• Provide mentorship paths
• Recognize first-time PRs

17. Building Inclusive Communities

• Welcome diverse backgrounds (physics, CS, math)
• Provide translations or multilingual tutorials
• Use gender-neutral language in code and docs

18. Moderation and Review Etiquette

• Respond constructively
• Encourage consensus
• Rotate maintainers to avoid burnout

19. Encouraging Feedback and External Resources

• Link textbooks, lecture notes, YouTube tutorials
• Invite community suggestions
• Offer channels (Slack, Discord, Discourse)

20. Conclusion

Well-crafted documentation and clear community guidelines are essential pillars of successful quantum software projects. They enable collaboration, reduce onboarding friction, and foster a welcoming and diverse contributor base that can advance quantum computing together.