Redesign GraphQL.org's homepage

[Urigo]

Find the latest designs here

Find our new messaging for GraphQL in order to put it on the main homepage

Current thinking:

Add to the homepage not only what GraphQL is but also its value proposition.

• Main hero section - "The Query Language for Modern APIs"
  • Add 3 main value propositions:
    • The best app user experience
    • Security and stability
    • Efficient distributed development
• Second section - Used at scale by the world's leading companies (logos....)
• 3rd section - what is GraphQL
  • similar to what we have today
  • Describe your data, Ask for what you want, Get predictable results
  • Link to how it works on another page
• 4th section - why businesses choose GraphQL
  • 3 value propositions
    • The best user experience (to show the unique benefits of GraphQL on client applications)
    • Security and stability (show the unique benefits of GraphQL in managing API changes, strict schema and automated security features)
    • Efficient distributed development (To show the benefits of teams taking different parts of the schema while using automated tools to sync their work into a single GraphQL schema)
• 5th section - The 5 pillars of GraphQL
• 6th section - Data Colocation - demonstrating GraphQL's unique ability to manage frontend data at scale
• 7th section - is GraphQL right for me
  • A list of use cases and if GraphQL is the right choice
  • Possible use cases:
    • A large backend with many services
    • A mobile app
    • A frontend heavy app with advanced UI and user needs
    • An app with real time updates
    • A simple full stack Typescript app
    • Something about AI
• 8th section - testimonials
  • From (hopefully high rank individuals companies from Meta, Netflix, booking.com, AirBnB, GitHub and others)
• 9th - community section - leads to all our community resources

[saihaj]

I would switch order of 2&3 and 5 & 6.

[JoviDeCroock]

Something I have missed in almost every value proposition section about GraphQL ever are the pillars of GraphQL. These really paint a good picture about expectations and make clear that GraphQL focusses on the product, it's not just any query language, it's a query language for your product, regardless what medium that product runs on.

[doc-jones]

First, what I like about this outline is the thought that has gone into it and how useful it is for discussion. There's a good balance between educational content and marketing/promotion of GraphQL.

I, also, find that I have opinions. :-)

I would delete Section 5, because most decisions that are made of what technology to use aren't based upon this technology versus that technology for building APIs. From what I've observed across teams and customers is that often a technology is selected because the team that implemented it wanted to use it. They may have personal opinions about the ease of adoption for REST, or they have never deployed GraphQL before, so choose it for that reason (i.e., new shiny thing). Larger enterprises most frequently have all available technologies represented on their network as various teams across many years have made different choices. Rather than a chart of competition between API styles, I would love to see information on how API styles can be used together or complimentary to one another. I think it is important for GraphQL to be more forward thinking as the realities and complexities of modern data requirements have changed.

Would it be possible to update graphql.org in stages? This thought occurs to me because, if we were to collect information from across the community and more broadly across adopters representing different industries, corporate sizes and uses cases, this information would inform what would be most helpful to add in sections of the website. There are new developments and uses for GraphQL developing as knowledge graphs become a critical piece of systems using AI/LLMs particularly for large enterprises. GraphQL is being implemented and integrated in new and complimentary ways across blockchain systems. New protocols are being developed to enable communication between AI agents and APIs. Questions to be answered include how well does the GraphQL spec and tools support all of these new uses. Perhaps? The data can direct us.

I love @martinbonnin 's discussion of building a survey #30 . A survey that is thoughtfully constructed and well promoted would give us not only a excellent way to engage and broaden exposure of the community to more adopters, but also create a wealth of content to clip and share across all GraphQL Foundation channels including the website over many months. Maybe even to new channels.

Section 6 and 7 we might consider combining these, but only after gathering data from a large survey effort and a collection of adopter case studies. More about this soon, I hope.

Section 8 is chef's kiss - perfection!

[Urigo]

@JoviDeCroock Love it!
where would you position these and what would you write about them?
Can you add this to the proposal above?

@doc-jones about section 5 - I knew its going to be controversial :)
I agree with your assessment on why technology is selected in teams.
The reason I wanted to add this to the discuss is that currently these table are everywhere and they are being written in a way that doesn't serve us justice.
This is an opportunity to add our perspective into that conversation and do it in the way that you described - not as a competition but to give more context then the alternative tables out there currently provide

About the stages - of course - the website is always a moving and evolving project.
I would always favor moving forward with what we know while gathering more information on the new use cases you've mentioned. Once we'll get that information, we can and should add it to the website!

Excited on making progress here!

P.S.
In a similar fashion to the "Bias towards action" and moving forward with what we currently know, and the fact that the website is always an ongoing project, I would also want us to always think if the proposed change is better then what we have today, not if its perfect

[martinbonnin]

Can we have a big "TRY IT OUT" call to action with a GraphiQL embed on the main page? I know we have it in other pages but:

• Some people never leave the home page
• Took me 8 years to realize that those elements were interactive. For some reason, I always assumed they were non-interactive.
• Everyone I talk to loves GraphiQL. Sounds like a big selling point for GraphQL.

[benjie]

I'd love to see that big "try it out" somehow integrated with the component based model of rendering, demonstrating clearly the value of fragments. I think too many people sleep on fragments, we don't do a good job of selling them up front, and too many people think they need to select everything manually and build massive "mega fragments" that all their different components use even though each component may only need a couple of the fields.

[andrewmcgivery]

5th section - comparison table - compare to other protocols (REST with OpenAPI/JSON schema, gRPC)

Dropping in just to say I'd love for this to have some nuance around GraphQL doesn't necessarily replace your other APIs (REST, GRPC, etc) but rather can be a great way to augment and magnify the investments you've made into those APIs.

So much of the problematic "debates" and GraphQL-hate often stems from this "comparison" of which one is "better" when in reality where we see the most success in large enterprises adopting GraphQL is to use GraphQL as the "middle" layer between the UI and service layer... using them together instead of pitting them against each other.

In my opinion, this message of "better together" is a much more productive, de-escalating, and winning message for GraphQL than "why is GraphQL better than REST".

This talk from API World is a great discussion on this exact topic: https://www.youtube.com/watch?v=5DVi99KPALo

[Urigo]

@benjie do you have an idea on how to best demonstrate these points visually and textually?
#21 (comment)
I'm thinking maybe we could use ideas from these two talks:

1. https://youtu.be/9sc8Pyc51uU?si=xKBfZFgDblRsmHTM
2. https://youtu.be/WxPtYJRjLL0?si=81oT3W7byWvNi4qx

[Urigo]

@andrewmcgivery wow, that's one of the best talks I've seen, thank you so much for sharing!

I very much agree with everything you said in your comment and the messages in the video.
I would love your help thinking on how we can integrate these messages into the new home page!

Looking at the table, let's say we change the format of it, but keep the point there, some are related also to the points from the talk, how do we present them in the best way?

Some thoughts on replacing section 6, I wrote while watching the talk:

1. The focus on the middle layer and how to manage it at scale. I would love to visualize it on the main page. I think its related to two of the three main value propositions we want to talk about - Security and stability and Efficient distributed development. I'm thinking where could we use similar visualizations from the talk on the main page

Taking points from the table, that we might drop or integrate as they are related to this part:

• Distributing development of services across teams
• API usage reporting
• Managing versioning and changes of the API

2. The other points from the table that are not covered by the talk, do we want to include them or maybe some of them already are covered by other sections:

• Strict schema
• Managing UI data requirements in components
• Consumers and clients ease of use
• Performance
• Ecosystem tools
• Something about AI

[erikwrede]

Expanding on @benjie's comment

I think too many people sleep on fragments, we don't do a good job of selling them up front, and too many people think they need to select everything manually and build massive "mega fragments" that all their different components use even though each component may only need a couple of the fields.

In my opinion, we need to motivate fragment use differently. Many newcomers to GraphQL are not aware of the best practice of UI-Component-driven queries. We don't do a good job at all of selling the synergies between GraphQL and the actual frontend hierarchy. Otherwise, we would not see so many people expecting GraphQL to just be a database-like query language for API queries, or implementations using GraphQL like a rest API - heavily abstracted away from the view and fetches split up into many queries. From a very critical perspective, the learn page reads like an introduction to SQL, not like the introduction to a powerful tool that can revolutionize the way you define, consume and utilize APIs to build next-generation apps.

Part of this is due to our strive to be as vendor- & tech-neutral on the main pages selling GraphQL. The aforementioned synergies are mainly enabled by tooling, no matter if open-source or by vendors. We are going to have a hard time showing the intuition of fragment-driven queries if we abstract away from the hands-on intuitiveness that a concrete example brings.

Is this complete abstraction away from implementation a point we could put up for discussion? I'd personally favor a well-balanced approach that sprinkles concrete technology examples into the page, while staying neutral in that we don't unfairly position any tooling over other options.

This is mainly something to discuss for the other subpages, but it could very-well affect small portions of our landing page. I'd be curious to hear your opinions on this intentionally challenging take 🙂

[Urigo]

@erikwrede I think you are right and I also think this today is a generally agreed upon idea by the leaders of the community

I don't think that the reason its not highlighted right now is because of vendor- & tech-neutral thing..
All vendors and popular clients today support these patterns today

I think the main reason is just that nobody did it yet :)

So let's split that into two things:

1. What do we want to say about it on the main page - can you suggest something concrete to the structure on the first comment that could bring these ideas more? For me, the sections where I wrote The best app user experience, some of the 5 pillars, Managing UI data requirements in components, A frontend heavy app with advanced UI and user needs - where exactly added to highlight that quality of GraphQL that no other API spec has
2. Bringing more of that content into the rest of the website (tutorial, docs, etc). For that let's open a new issue

[benjie]

I don't think we have to be particularly vendor-specific in this - React, Vue, Angular, SwiftUI/UIKit and Jetpack Compose (I think?) are all component-based systems that would pair nicely with fragments. I think we can show component-based UI and GraphQL fragments without needing to be vendor specific at all; but I'm afraid I don't have the design skills to actually pull something like that off.

[erikwrede]

Thanks for clarifying @Urigo 😊

Regarding

1. We could have an interactive view with a demo app on the left - hovering over each ui element reveals its fragment on the right, and a slogan like "Connect Components Seamlessly with GraphQL Fragments". I don't either have the design skills to pull this off, but we could ask some AI tool to try and draft it for us. Something like this, but in pretty (I did not check any components for correctness, just a sketch 100% ai generated): https://v0.dev/chat/graphql-fragment-demo-R2N7Q9Bq8aK?b=b_xpQLeHGAjRy or https://v0.dev/chat/fork-of-graphql-fragment-demo-GV1daBRhWEp?b=b_S53JTL1VB93
2. I'm writing up a separate issue. Will post later

[benjie]

@Urigo If we could boil down the key points in that first video (but modernised and not Relay-specific) into our homepage I think that'd be amazing! Honestly this diagram itself is quite effective at demonstrating the concept behind fragments:

I really like Erik's v0 mocks too, though if the fragments are concrete I'd want to see something representing the data from the fragments within the components too, to make it more real.