Skip to content

Design a user-facing problem catalog/table entrypoint #61

@cmccomb

Description

@cmccomb

Summary

Design a clearer user-facing catalog/table experience for design-research-problems, potentially with separate entrypoints for catalog browsing versus API/reference usage.

Why

This repo is the main outlier in the module family: users often want to browse what problems exist before they care about the Python API details. Right now that catalog story is not prominent enough in the docs.

Questions to resolve

  • Should the docs have separate high-level entrypoints for:
    • browsing the problem catalog
    • learning the library / API surface
  • Should the catalog be presented as a generated table, matrix, or searchable summary page across families?
  • What metadata should be visible at a glance for each problem family or packaged problem?
    • family
    • compute requirements
    • optional dependencies
    • interfaces / entrypoints
    • canonical examples

Proposed work

  • Add a user-facing catalog landing page or section that is clearly different from the API reference.
  • Provide a concise table or matrix that helps users compare problem families and find the right entrypoint quickly.
  • Evaluate whether the docs should split into separate entrypoints such as “Catalog” and “Reference/API”.
  • Make sure the final information architecture still works cleanly inside the shared PyData-based docs shell.

Acceptance criteria

  • There is a documented information architecture decision for catalog browsing versus API/reference browsing.
  • The docs expose a clear user-facing catalog/table for the packaged problem space.
  • A new user can answer “what problems are available and how do I start?” without reading the full API reference.

Metadata

Metadata

Assignees

No one assigned

    Labels

    priority:normalNormal scheduling prioritystatus:readyReady to starttype:docsDocumentation additions or corrections

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions