Skip to content

Improve docs site landing pages/versioning experience #76

Description

@cassidyjames

Right now we use effectively the same mdbook workflow to build versioned docs sites for both Coop and Osprey:

The versioning is a little awkward UX-wise:

  • The index page doesn't look great; it's barebones and looks like it's not meant for humans 😅
  • When in the docs, it's not obvious which version you're browsing without looking at the URL
  • When browsing old docs, it's not obvious you're not browsing the latest (which might be on purpose, but you should be doing it consciously!)
  • /latest is the latest unreleased docs; there's no /stable for the latest release

I don't mind the mdbook-generated sites themselves, but I think we could improve this with a few changes:

  • Add a /stable symlink to the latest released version of the docs
  • Add the list of versions to the built mdbook site itself (i.e. a list on the index and/or a drop-down in the nav bar) instead of a standalone index page
  • Redirect / to either /stable or /latest (I could be convinced either way)
  • Consider adding an alert bar to old docs to flag that they're not the latest version, and to /latest docs to flag that they're for the unreleased version

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomers

    Type

    No type

    Fields

    Priority

    None yet

    Projects

    Status
    Todo

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions