Skip to content

Feat/53/website redesign notes #54

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
SensibleWood wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Feat/53/website redesign notes #54

Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f2fde43
chore: Add initial revision
SensibleWood Nov 1, 2025
9aec14d
chore: Revert errant changes to prettier config
SensibleWood Nov 1, 2025
e520145
Update src/website/design/content-redesign-notes.md
SensibleWood Nov 7, 2025
79d7393
Update src/website/design/content-redesign-notes.md
SensibleWood Nov 7, 2025
0949470
chore: Updated website notes
SensibleWood Nov 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 92 additions & 0 deletions src/website/design/content-redesign-notes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
# Website Layout

This document provides an overview of the content design for the revised openapis.org website.

## Menu

This section provides the content of the menu bar.

### Drop downs

The following are the drop downs we should aim for.

```text
Learn
Copy link
Member

@pavelkornev pavelkornev Nov 5, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shall we add Tooling under Learn? Or we can add something like Ecosystem, where we can have learn materials + tooling

Copy link
Member

@handrews handrews Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ooh I like ecosystem! But will that draw the right attention?

├── What Is OpenAPI? (Relocate existing page).
├── [Learn About OAI](https://learn.openapis.org/)
├── [OAI Courses](https://training.linuxfoundation.org/full-catalog/?_sf_s=openapi)
Specifications
|
├── [OpenAPI](https://spec.openapis.org/oas)
├── [Arazzo](https://spec.openapis.org/arazzo)
├── [Overlay](https://spec.openapis.org/overlay)
├── [Registries](https://spec.openapis.org/registry/)
Community
├── [Collaborate on Slack](https://communityinviter.com/apps/open-api/openapi)
Copy link
Member

@pavelkornev pavelkornev Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We're going to have Slack/GitHub icons. Do we need a dedicated menu item for Slack? Though, i think it might be important to have a page to describe how collaboration happens in OAI. E.g. the main communication channel is Slack, it's divided into sub-channels for each spec/SIG, etc. Also, how to join community meetings, not everyone knows where to find this information.

├── Participate
├── [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/README.md#participation)
├── [Arazzo](https://github.com/OAI/Arazzo-Specification?tab=readme-ov-file#getting-involved)
├── [Overlay](https://github.com/OAI/Overlay-Specification)
├── Current Members (Relocate existing page)
├── Become a Member (Relocate existing page)
Events
Blog
```

## Homepage

Proposed design notes for homepage.

### Banner

> Looking at the top section of https://graphql.org/ for inspiration here, think the headline section works really well.

Title: API Description Languages for the API Economy.

- Open, language-agnostic API description with the OpenAPI Specification.

- Extend descriptions to multistep API-driven workflows with the Arazzo Specification.

- Automate maintenance and increase efficiency with the Overlay Specification.

The OpenAPI Initiative supports the development of the OpenAPI, Arazzo, and Overlay Specifications, which are trusted by millions of developers when creating, describing and consuming APIs.

> HERE LETS HAVE A CAROUSEL OF MEMBER LOGOS THAT AUTO TRANSITIONS RIGHT TO LEFT, SHOWING MEMBER LOGOS
> Button under the carousel - "All Current Members" - goes to https://www.openapis.org/members
Copy link
Member

@handrews handrews Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this part of the member value proposition? Because otherwise, it is permanently ceding tremendously valuable screen real estate to a single purpose. Also, not all web pages need a carousel. It's usually used when you are trying to sell things and want to put different options in front of visitors immediately, in a way that can be updated quickly.

Our list of members does not change very often, and what benefit do we get from routing traffic to them? Again, if that's part of our member value proposition that's one thing, but eating up this part of the web site has a big cost.

It's more common to see a grid of members/contributors/sponsors further down. If we must have a carousel, it should be used to highlight timely events and announcements that we want users to take action on.

Copy link
Member

@pavelkornev pavelkornev Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree on the carousel for announcements... e.g. events, new spec versions, or maybe even new members... e.g. Jentic just signed up to support OAI, there was a post on LinkedIn, in addition we could have a banner in a carousel for a month on the main page or so as part of the package for new members.

Copy link
Member

@handrews handrews Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pavelkornev yes, announcing a new member would be a good use, as it's a transient but important thing to highlight.

Copy link
Member

@handrews handrews Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pavelkornev I also talked with a UX consultant who said "carousels have been considered bad UX/accessitibility since 2010" and very strongly recommended against using one. I notice that the GraphQL site is given as an example of a good API-related site, and they do not have a carousel. Why do we want a carousel when it is an outdated interface with problematic UX and accessibility issues?

Copy link
Member

@pavelkornev pavelkornev Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@handrews Chris just created a first draft — nothing is set in stone. We’re free to do what we think makes sense. If you have any proposals, feel free to speak up; now’s a good time.

Copy link
Member

@handrews handrews Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pavelkornev I know this is just a starting point, my proposal is "don't use a carousel" :-) Here's more information and research about why carousels aren't just bad UX, they actually reduce impact and visitor engagement.

My goal in bringing in this information is to ground the conversation in something other than personal opinion. It's not that I personally dislike carousels, although I do tend to ignore them. It's that i want our site to feel modern and accessible, and I want it to engage our users with the right content.

So I am presenting evidence that using a carousel at all goes against all of those goals.


### Main Section

> These are just rough ideas, to iterate over some content for the page. Ignore the formatting, it's the layout calls to action that are important.

<div style="display: flex; gap: 1rem;">

<div style="flex: 1; padding: 1rem;">
<h2>Why Use OpenAPI?</h2>
</div>

<div style="flex: 1; padding: 1rem;">
<p>OpenAPI is the foremost API description language available to the API community today, and powers how knowledge of APIs are shared between API creators and the organization that use them. OpenAPI is a rich, vendor and programming language and vendor agnostic language, that reflects how APIs are created and published, and is supported by a huge and vibrant tooling community.</p>
</div>

</div>

> Here an overview diagram that lays out view of where OpenAPI

### Footer

Much of this content will be relocated from existing pages...

- See the Audit Section that provides list of pages to be relocated.

## Audit

This is intended to provide an overview of where pages go from and to.

Not complete, will be gradually updated as this work progresses.

| Page | Location | New Location | Actions | Location |
| ----------------------------------- | -------------------------------------------------- | -------------------------------------------- | -------------------------------------------------------- | ----------------- |
| About | Menu > About > About | Footer > About | | /about |
| Technical Steering Committee | Menu > About > Technical Steering Committee | Footer > Technical Steering Committee | | /governance/tsc |
| Code of Conduct Transparency Report | Menu > About > Code of Conduct Transparency Report | Footer > Code of Conduct Transparency Report | | /governance/coctr |
| _All Specifications Menu Items_ | Menu > Specifications > \* | As per new Menu design | Anything not listed in the Menu section above is removed | N/A |