Feat: Define and agree new top‑level menu structure for openapis.org #68
Description
Parent: #67
Summary
As part of the repositioning work in #67, we need the new site navigation to reflect OAI as an organisation stewarding multiple specifications and a community rather than just as a download/resource site for the OpenAPI Specification.
This issue proposes a simple top‑level menu structure and explains the thinking behind it, so that design and content work can move forward with a shared view of how the site should be organised.
Note that I haven't given specific menu titles for the items that would be included under the top-level items, but simply explained in words what kind of resources might sit there. The exact verbiage can of course be confirmed and clarified once we agree on the top-level headings/collections.
Proposed top‑level menu
About
Our specifications
Ecosystem
Learn
Get involved
About
Purpose
Explain who OAI is, why it exists, and how it operates. This answers the 'what is the OpenAPI Initiative?' question at the organisational level, rather than 'what is OpenAPI?'.
Likely contents
- What is the OpenAPI Initiative
- Governance (TSC, BGB, SIGs overview)
- Community structure / how we work with the Linux Foundation
Reasoning
At the moment, many people only associate OAI with the OpenAPI spec. Leading with an 'About' section that tells the organisational story helps reset that first impression - OAI is a consortium and community, not just a spec or a repo.
Our specifications
Purpose
Present the portfolio of specifications OAI stewards in one place and make it very obvious that we are not a one‑spec organisation.
Likely contents
- OpenAPI Specification
- Arazzo Specification
- Overlay Specification
- Registries (and how they relate to OAI specs)
- Short 'how they work together' overview
Reasoning
Right now, the site reinforces the idea that OAI = OpenAPI. Listing OpenAPI, Arazzo, Overlay (and registries) together under 'Our specifications' makes the multi‑spec story explicit and gives us a natural place to link to spec docs, release notes and roadmaps.
Ecosystem
Purpose
Show that there is a living ecosystem around the specs - members, SIGs, events, tools - and give that space its own home.
Likely contents
- Members and adopters
- SIGs and working groups
- Events and collaborations (for example OAI tracks at conferences)
- Case studies / 'specs in practice'
- Tools and integrations
Reasoning
We talk a lot about 'ecosystem' and 'community' but the current site doesn’t really reflect that. A dedicated 'Ecosystem' area allows us to celebrate members, highlight real implementations and point to related tooling, without overloading the Learn or About sections.
Learn
Purpose
Be the home for all the 'how do I actually use this?' material - from getting started to best practices and recordings.
Likely contents
- Getting started with each spec
- Best practices and design patterns
- Recorded talks and tutorials
- Training and clinics
- Blog
Reasoning
This is where 'What is OpenAPI?' and similar educational content should live. Keeping it under Learn (rather than as the default homepage experience) avoids conflating 'what is the spec' with 'what is the organisation' and supports the content strategy around thought leadership and specs in practice.
Get involved
Purpose
Make contribution and membership pathways very clear, for both individuals and organisations.
Likely contents
- Contribution pathways (issues/PRs, SIGs, docs etc.)
- How to join and participate in SIGs and working groups
- Become a member (link to membership benefits page)
- Speaking and writing opportunities
- Community links (Slack, GitHub, meetings)
Reasoning
We already have multiple entry points (Slack, GitHub, SIGs, membership, events) but they are scattered. A 'Get involved' section gathers them in one obvious place and supports the 'getting involved' content area from the repositioning work – making it easier for people to move from user → contributor → member.
Next steps
- Confirm these are good as top-level headings
- Identify if there are any top-level headings missing
- Once agreed, create sub-issue/s if needed to determine sub-page content