Relay: Relay Docs is one of the hardest docs I ever tried to understand

[ashah888]

Relay Docs are ridiculous hard to understand.

It lacks examples.
It lacks clear explanations.
Unclear, scattered variables in examples.

[BilalBudhani]

As someone who is trying to understand how to implement Relay, I can relate to this and second the OP.

[nodkz]

I agree with you. But after several months I found doc very condenced. I totaly reread it about 5 times ;)

[KyleAMathews]

Errr... what the hell?

There are real people behind Relay who've put an enormous amount of effort into documenting Relay. At least try to respect that.

Relay is an ambitious new project. And despite the OP's comment is abundantly documented with 3-4 working examples, extensive API docs, numerous conference talks, blog posts, etc. I would love it if all Open Source code I use was documented and supported this well.

If you have constructive, detailed, _respectful_ feedback about what you've found difficult to understand while learning Relay, I'm sure people here would love to hear that. But your comments so far are not the least bit helpful and are frankly pretty offensive.

[KyleAMathews]

And I apologize if that came across as too harsh. Your perspective is valuable and needed for Relay to be successful. It really would be valuable to hear your stories of what and where you struggled.

I'm not a Relay maintainer but I know what it's like to be receive these sorts of comments and it's not fun.

[wincent]

Thanks to everybody for chiming in on this thread. We'd definitely like to improve the documentation, and do what we can to make Relay easier to understand. Like @KyleAMathews said, however, in order to be most useful, we need the feedback to be a little more concrete, focused and actionable. I'm going to close this one for now, and I encourage you to open narrower issues for specific problems that you find with the documentation or the concepts in the framework. The more detail, the better, and best of all is if you can incorporate a concrete suggestion for how something could be changed into a format that would be more understandable and useful to you.

(Also feel free to comment on this issue, even though I am going to close it. I'm just closing it because it is not specific enough to be actionable, not because I want to silence the discussion.)

[nodkz]

@KyleAMathews nobody say that doc is terrible. Just say that it is "hard to understand". And it really such is. Because Relay has huge amount of abstractions/logic/relations and especially in conjunction with graphQL, so brains should hard strained to catch all aspects and principles how Relay works. So I can not imagine examples, which can give easy dive to Relay.

I found doc very condensed (absent vacuity). So need read every topic attentively, cause every paragraph contain concentrated (high amount) information. And I spent seconds to find needed information. So for me at now doc is very good, for me at past doc was how @ashah888 wrote above.

Framework is too fresh, and of course is written low amount tutorials for newbies. Just need wait a critical mass of audience and success projects outside facebook.

PS. I am spent 7 months to study from scratch NodeJS + ES6 + Webpack + React + Relay + GraphQL + and tons of other modules (after Dan's talk at React Europe 2015 about hot-reload). So beautiful and simplicity have hight price. BTW I'm very glad that I ran away from RoR. Glad that choose Relay, not Redux. Glad how FB invested resources to open source and what amazing peoples maintains it. Especially inspired by eminence grises - Sebastian Markbage and Lee Byron.

[BerndWessels]

There are plenty of Relay Git Issues here about the fundamentals and understanding of the nitty gritty of Relay that got shut down with the comment that they are noise and better placed at StackOverflow. Unfortunately often they are then not answered on StackOverflow. And from my personal experience there are many areas in Relay that are either not documented or very poorly explained.

The risk here is that people get all excited about GraphQL and they should! But then when it comes to Relay they get disillusioned about the complexity and how hard it is to use GraphQL on the client.

So Relay can drag down GraphQL's success. I experienced it myself. I convinced my company to use GraphQL. Everybody loved it until people got extremely frustrated with Relay. It almost killed GraphQL in our company. I could only save it by dropping Relay and build a much simpler and easier to use and understand client site GraphQL connector.

Obviously we all appreciate the huge effort of all the people working on Relay - but maybe there should be a warning on the Git Readme saying "Work in progress, not ready for production yet".

[brad-decker]

Our company has successfully implemented a fully working Relay website using the documents provided and a little sleuthing inside the source code. It's my opinion that more documentation and better documentation is ALWAYS possible but that doesn't meant that it is not usable to produce a working product.

@Aweary @dwightbe :+1: :+1:

[KyleAMathews]

Relay seems like an excellent example of a _simple_ tool that's not necessarily an _easy_ one (using Rich Hickey's framework).

It's certainly not easy to get going with compared to using existing, familiar tools e.g. REST but is incredibly _simple_ to use once you get it and things are setup. For my product, Relay is the most carefree part of the stack and just works. Creating new components is a breeze.

Or to use economic terminology. Relay has a high fixed cost but very low marginal costs.

My assumption is over time the fixed cost will drop but as far as I'm concerned, Relay has by far the lowest marginal costs in the data-fetching industry.