Feat/53/website redesign notes #54
There are no files selected for viewing
| 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 | ||||||
| ├── What Is OpenAPI? (Relocate existing page). | ||||||
|
There was a problem hiding this comment.
Suggested change
To avoid confusion with the specification itself. We can explain all 3 specs briefly on that page. |
||||||
| ├── [Learn About OAI](https://learn.openapis.org/) | ||||||
| ├── [OAI Courses](https://training.linuxfoundation.org/full-catalog/?_sf_s=openapi) | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| 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) | ||||||
|
There was a problem hiding this comment. 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 | ||||||
|
Comment on lines
+54
to
+55
There was a problem hiding this comment. 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. There was a problem hiding this comment. 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. There was a problem hiding this comment. @pavelkornev yes, announcing a new member would be a good use, as it's a transient but important thing to highlight. There was a problem hiding this comment. @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? |
||||||
|
|
||||||
| ### 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 | | ||||||
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
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 + toolingThere was a problem hiding this comment.
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?