Relay: Docs: Re-designed landing page for Relay

[orta]

👋 - continuing my design work on the Artsy Omakase stack: https://github.com/prettier/prettier/issues/3669 https://github.com/facebook/jest/issues/7265

Like with the re-designs above, this issue is a call-to-action for someone to help out in building the design - I'm happy to come in once there's some WIP and help out but I'd rather live in design world first.

This keeps the same logo, and color scheme - I like the simplicity of the Relay logo (and how it fits with what Really does) and the color scheme doesn't offend me. That said I don't use the orange that much In here outside of the large header, so, eh, whatever it's mostly a highlight color in my mind.

What were my goals?

• Describe Relay succinctly, and define how it differs from most API clients
• Try give an overview of the API surface
• Re-define the phrasing around a relay-compatible GraphQL server ( also https://github.com/facebook/relay/pull/2603 https://github.com/graphql/graphql.github.io/pull/666 https://github.com/graphql/graphql.github.io/pull/665 )
• Try to explain why there's more tooling than peeps might be used to in the JS world
• Offer counter-balances to why you might think it's all a bit much
• Prime people for Relay's (current) model of OSS support
• Improve the social proofing

I explicitly aimed for much more toned down design in favor of the more colorful other designs, Relay feels like serious work,

Link to explore

on Figma

Desktop

Mobile

Coming later

Notes

• I want to think about the ordering of the grey/white sections and if I can improve that somehow, I used to have an orange section but it was all a bit much. Maybe a black or dark grey section could work, but it'd need to be worth the visual distinction.
• Will follow up in a comment with the ideas for that above the fold animation
• Perhaps a revised Relay logo could reference the GraphQL logo, it's an avenue I've been debating, but my pencil sketches haven't turned up anything good yet
• Thanks @eliperkins for white-boarding initial ideas and figuring out some of the info hierarchy

[orta]

So roughly, the idea is to compare Relay's declarative data deps approach vs imperative passing of the data through props.

The first section explains how in you normally make a big request, then pass subsets of it through the tree:

Basically, something like this but recursive:

Thanks @zephraph

Then the relay version talks to how you have each with their own shapes. I explored having these shapes be subsets of the full request ( e.g. one might be a half of the full hexagon, another a concave shape) and I really couldn't make that look good.

Instead, I opted for smaller objects that could all be created from the original hexagon by deleting points. This looks nicer, and hints at the idea that each bit of data is smaller in theory but it's not too strong of a correlation.

In my head this kinda does that video-game-y "you've collected all the things" bring them all to the front and spin them to make sure you notice thing. I think it could do one full rotation to represent a full load and then fly back into the original places fully filled.

Both of these are a bit more word-y than I'd like. Would love ideas on optimizing word-count here, or even better metaphors. Though I think the animations can just take some time to give folks time to read.

I think the animation should run through once, but maybe only start once you actively scrolled as it's not the first thing you would look at (especially considering how orange the headline is)

It'll probably need a reset mechanism too, maybe that's just a refresh-style button once it's done

[eliperkins]

I started poking at this a bit with the existing Docusaurus implementation, mainly just updating copy and a couple little styles: https://github.com/facebook/relay/compare/master...eliperkins:new-site-poc?expand=1

I'm happy to keep plugging away at this, if folks are keen on this direction. It could be nice to add more to the site in smaller steps, to improve what we've got already and add more as folks are able to/as we review and discuss things.

I'd certainly need a hand on animation bits, as that's not really my forte.

[soneymathew]

@orta This is great already 👏 👏 👏 This will greatly help towards understanding relay a lot faster for new adopters

Would you consider demystifying a few more complex stuff like transformations applied to the query
The compiler aggregated query consolidating fragments, passes thru a couple of transforms enriching/optimising it further. http://facebook.github.io/relay/docs/en/compiler-architecture.html

Few internals are explained by @wincent here
https://speakerdeck.com/wincent/relay-2-simpler-faster-more-predictable

Would be nice to cover possibility of persisted queries , new @match directive etc

[soneymathew]

I had a thought about enabling Visual learning from the following perspectives?

Design Time perspective

Wireframe -> UI Design -> Component Hierarchy -> graphql fragment per component

At Component Hierarchy level help differentiate between FragmentContainer, RefetchContainer, PaginationContainer, QueryRenderer
something akin to what you have done here https://artsy.github.io/blog/2017/07/06/React-Native-for-iOS-devs/#React

Build/Compile time perspective

perhaps an animated pipeline?
Compiler -> Aggregated Query -> Strip client schema extensions -> FlattenTransform -> SkipRedundantNodeTransform -> GenerateRequisiteFieldTransform -> PersistedQuery as an optional step -> hint at a possibility of making persisted query available to server

Runtime perspective

Fetch -> Relay store -> Datamasking -> Distribution to components -> Garbage Collection on unmount

Mutation -> Optimistic Mutation -> Impact on multiple components subscribed to shared state -> Commit/Rollback -> Impact on multiple components subscribed to shared state

Subscription perhaps will be a repetition of query but could be a looped animation that can be paused or stepped thru perhaps?

[orta]

Hey sorry, I missed the first message!

So, I think things like transformers, runtime and the build process are not really the right items to put on the homepage - they're things you need to know once you're using Relay but not things that will help you decide whether _to_ use Relay. Valuable, yep, but inside the docs themselves.

The "Design Time perspective" is something that I had been wondering about for the "how does relay work" section in the design. My goal there was to provide a very high level understanding of terms that you'd start seeing the moment you jump into the docs ( e.g. FragmentContainer, RefetchContainer, PaginationContainer, QueryRenderer )

I'm still not sure if that section pays for itself yet though?

[soneymathew]

From my perspective, I am looking for a simple view and an exploded view that highlights the opinions that support the pit of success claim that will help make a strong case for relay.

[sgwilym]

I've come round to thinking that the success of any future Relay front page hinges on how well it explains how data is passed to components with Relay (and with other libraries).

I've mentioned to @orta that I think the hexagonal tree diagrams (which are already a massive step in the right direction) could benefit with being associated with a diagram with something a little more visceral — here's a rough mockup of what I mean by that:

This way I feel like you get a better idea of how the tree of data corresponds to a tree of components. I'd be interested to hear if anyone else thinks this helps/distracts.

[orta]

In the last two weeks I've not managed to think of a way to structure something like ^ in a way that doesn't require interacting to understand it, or that the extra illustration are worth losing the space where the text is.

I'm not sure it's better than the current scroll animation where the text flows in and diagram animates to highlight what the text is saying. I'm open to other ways of interpreting it, or having it in a separate space but it might be worth just saying this is pretty good to go overall and then I can take a final stab at the reading flow and mobile designs

[sgwilym]

Understandably you want to get on @orta — I don't want to bog down this effort. But I still think the abstractness of this diagram might not communicate what Relay is doing in tandem with React clearly, especially to new users. But perfect's the enemy of the good etc etc. 🙂

[totsteps]

Saw this tweet. I have basic knowledge of React, JS and CSS, but would love to give it a shot.

Thanks.

[orta]

Woo - awesome - I'd recommend getting started by getting a copy of the site running running locally and making a few changes to get it feeling good 👍

[luansantosti]

Hey @orta I want to help also, how is it doing so far?
I've already a copy running locally.

[orta]

Looks like I didn't leave a copy of the design anywhere (thanks for the ping @luansantosti) - here's a Figma doc with all my design work in - https://www.figma.com/file/NnzQcpGu8ulcLahR9tr70x/relay-website?node-id=0%3A37

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.