A quantum developer portal is part of the product, not simply a place to store reference pages. This release-by-release checklist helps research teams and software developers review installation, documentation, notebooks, terminology, access, errors, search, versioning and support so that a quantum SDK remains understandable and usable as it changes.
Overview
Quantum software often brings together unfamiliar concepts, specialised hardware constraints and conventional software workflows. A developer may move between an SDK, a hosted platform, notebooks, command-line tools, API references and research documentation in a single task. Small inconsistencies between those surfaces can create avoidable friction: an installation command may point to an outdated package, an example may use a renamed method, or an error may describe a technical condition without suggesting what to do next.
Good quantum developer portal UX reduces this friction without hiding necessary complexity. It gives users a reliable path from first task to independent work, while making changes visible to experienced researchers and engineering teams. The review should therefore assess both discoverability and accuracy. A polished interface cannot compensate for an example that no longer runs, and comprehensive reference material is difficult to use if its structure does not match the way people work.
Use the checklist below before a major SDK release, platform redesign, onboarding campaign or documentation migration. It can also serve as a monthly or quarterly health check. Record the result, the affected version and the owner for each action so the review becomes part of product operations rather than a one-off editorial exercise.
What to track
Track a small set of recurring variables that show whether the portal still supports real work. The precise measures will depend on the product, but the following areas provide a practical baseline.
| Area | What to check | Evidence to record |
|---|---|---|
| Information architecture | Can a new user find installation, quickstarts, concepts, API reference, tutorials, notebooks and support without knowing the product vocabulary? | Navigation path, broken links, duplicated pages and unresolved search terms. |
| Installation paths | Are package, command-line, hosted and local setup instructions clearly separated? Are prerequisites and supported environments stated for the relevant release? | Fresh-install result, command output, environment notes and last verified date. |
| API terminology | Do method names, parameter labels, qubit terminology, circuit concepts and result descriptions remain consistent across guides and reference pages? | Terminology exceptions, deprecated names and glossary changes. |
| Code examples | Can users copy, run and understand the examples? Do they show expected output and explain assumptions? | Run status, SDK version, missing imports, output differences and reviewer. |
| Notebook workflows | Are notebooks easy to launch, reset and repeat? Do cells run in sequence, and is any required authentication explained near the relevant step? | Notebook run-through, execution time concerns and setup blockers. |
| Authentication | Are account creation, credentials, permissions and environment variables explained without exposing secrets in examples? | Successful test path, failure path and links to account or access guidance. |
| Error messages | Does each common failure explain the likely cause and a next action in language users can act on? | Message text, trigger, suggested fix and whether the issue is reproducible. |
| Documentation search | Do common queries return the right page, current version and relevant terminology? | Test queries, top result, search refinements and zero-result terms. |
| Versioning | Can users identify the version covered by a page, compare changes and find migration guidance? | Version label, release notes, deprecation notices and migration links. |
| Support routes | Is it clear where to report a defect, ask a usage question or request clarification? | Route tested, expected response information and duplicate support paths. |
Review the first-use path
Start with a task that represents a realistic first session, such as installing the SDK, running a small circuit, viewing results and changing one parameter. Follow the path as a user who understands software development but may not know the platform's internal terminology. Note every point where the user must guess which page to open, whether an instruction refers to a different interface or how an expected result should look.
Then repeat the exercise as an experienced researcher or platform engineer. This second pass should test less linear tasks: locating a specific API method, checking a compatibility note, switching versions, reproducing an error or finding details about execution constraints. A portal that works for beginners but frustrates returning users may need better search, cross-linking or reference-page structure rather than more introductory copy.
Check content and interface together
Scientific software UX design is not limited to page layout. Examples, labels, diagrams, warnings and interactive controls all shape the user's mental model. Check that visual terms match written terms, that screenshots show the current interface and that code blocks distinguish editable values from required syntax. For dashboards and notebook-based tools, use the same review principles: make state visible, identify units and assumptions, and avoid relying on colour alone to communicate status.
Cadence and checkpoints
A repeatable cadence keeps technical UX issues from accumulating. Use a deeper review around major releases and lighter checks between them.
Monthly check
- Test the main installation path from a clean environment or documented baseline.
- Run the primary quickstart and at least one maintained code example.
- Check the top support questions, search failures and reported documentation issues.
- Confirm that prominent pages display the correct version or status.
- Review links to authentication, access, support and release notes.
Quarterly check
- Repeat the full first-use journey across the principal user types.
- Audit a representative sample of API reference pages against the current SDK.
- Run notebook workflows from a clean session, including authentication and reset steps.
- Review terminology with a developer, researcher and documentation owner.
- Inspect error messages for common installation, access and execution failures.
- Test documentation search using real questions from support tickets, issues and onboarding sessions.
Release checkpoint
Before publishing a major release, create a small release-readiness record. Include the SDK or platform version, tested environments, changed APIs, removed or deprecated features, updated examples, affected notebooks, authentication changes, known limitations and support routes. Assign each item an owner and a decision: ready, needs correction, or needs a visible limitation notice.
Do not treat release notes as a substitute for in-context guidance. If a change affects how a user installs, authenticates, writes code or interprets results, update the page where that task occurs. Link the detailed migration guidance from the affected tutorial and reference entry.
How to interpret changes
Not every issue indicates a complete portal redesign. Interpret findings by asking whether the problem is caused by content, structure, product behaviour or an expectation mismatch.
- Repeated search failures may indicate missing synonyms, unclear page titles or terminology that differs between the product and the documentation.
- Users abandoning installation may point to hidden prerequisites, unsupported environments, confusing authentication or commands that assume too much prior knowledge.
- Frequent example questions often mean the example lacks context, expected output, parameter explanations or a clear next step.
- Errors that generate support requests should be reviewed for actionable wording, stable error identifiers and links to relevant troubleshooting guidance.
- Conflicting terminology usually requires a shared glossary and a decision about which terms belong in the public interface, not just isolated copy edits.
- Version confusion can signal weak labels, stale search results, missing migration links or a default version that does not match the user's task.
Prioritise issues by user impact and recurrence. A broken installation path, misleading API example or unclear authentication step deserves attention before a minor visual inconsistency. At the same time, repeated small inconsistencies can reveal a design-system problem. If buttons, warnings, code blocks or status labels behave differently across the portal, document the pattern and fix the underlying component or template where possible.
Keep product and documentation findings together. A confusing error may require an interface change; an apparently missing feature may be a discoverability problem; a tutorial failure may expose an SDK regression. Shared triage helps the team avoid rewriting documentation to explain behaviour that should be improved in the tool itself.
When to revisit
Revisit this quantum developer portal UX checklist monthly for operational maintenance and quarterly for a broader experience review. Repeat it whenever an SDK, API, authentication flow, notebook environment, hosted interface or documentation platform changes. It is also worth running before an onboarding campaign, partner integration, academic workshop or public demonstration, when a temporary increase in new users can expose unclear first-use paths.
Refresh the checklist itself when the product introduces a new execution model, adds a developer surface, changes versioning conventions or adopts a different support process. Update screenshots, code examples, terminology lists and test environments whenever their source interface changes. Mark each review with a date, version and owner; otherwise, a page can appear current while its examples quietly age.
For the next review, choose three concrete tasks: one installation path, one code or notebook workflow and one troubleshooting journey. Test each from a clean starting point, record the exact friction, assign an owner and set a follow-up date. That modest routine gives research teams and software teams a dependable way to keep technical UX clear as the underlying quantum product evolves.
For related governance and content checks, see the Quantum Software UX Design System, the Scientific Software UX Design Checklist and the Quantum Technology Website Content Audit Checklist.
