Easier navigation to graphql-js tutorial

[dortzur]

The entire section of http://graphql.org/graphql-js/ which contain the node.js tutorials isn't mentioned in the header or the footer of graphql.org. I think that's a shame since this section is very well written and frankly pure gold for anyone implementing with node.js.

I could only find links to the page though http://graphql.org/code/ and it's not that clear in there you're going to see a thorough tutorial. I think a link at least at the footer could be beneficial.

I found it only by googling.

I'll add that https://github.com/graphql/graphql-js readme clearly refers to this documentation.
references https://github.com/graphql/express-graphql readme file are a little more obscure.

[stubailo]

I think the "code" page could really benefit from a sidebar - that way you could click "code", then the sidebar could have a link to the graphql-js tutorial.

[lacker]

I was going back and forth with @leebyron about this & at some point during development had a sidebar with more stuff. I personally am a fan of linking to this from more places but Lee is kind of the site layout dictator here ;-)

[leebyron]

@dortzur - we're trying to avoid the existing preconceived notion that GraphQL is a Node.js technology, and I think that would be made more problematic by having solicited links to the Node.js docs in more prominent places than where we have links to implementations, while not having links to the Ruby or Java implementations, for example, which are both also heavily used.

/code/ is absolutely the right place for these links to live, as well as linking to the site from the graphql-js github and npm Readmes.

The /graphql-js/ section is in a little bit of a transitional state right now. It used to be part of graphql.org directly, and we're converting it into it's own site. Right now it still very much looks like graphql.org, but that will likely change in the future so graphql-js can have it's own visual style and destination landing page.

[leebyron]

One thing I think we can do to improve this is drive more traffic to the "Code" section, which the Node.js version is rightfully focused. I'll draft a change which helps people understand this to add to the "Learn" section.

[dortzur]

Giving it it's own website makes sense. And I understand where you're coming from not wanting to couple GraphQL to Node.js too tightly.

I still think the current state of the Code section has a "hidden gem" problem. For example snooping around I saw the Scala implementation http://sangria-graphql.org/learn also has a very nice tutorial mini-site.

I think this is a vastly different experience then when you click on the current Ruby implementation which directs you to the Github repo which currently only has a Github repo link https://github.com/rmosolgo/graphql-ruby.

What I'm trying to say I guess is that:
http://sangria-graphql.org/learn/
http://graphql.org/graphql-js/

Is substantially different than:
https://github.com/rmosolgo/graphql-ruby
https://github.com/graphql-go/graphql

As far as intro to GraphQL goes.

It could be beneficial to have a stronger indication which languages have these "tutorial mini sites", because those are pure gold as far as ramping up on GraphQL in your preferred language.

It could also encourage contributors to create these learning mini sites for languages that are still missing them.

If you read this far I've taken enough of your time. Thank you and please keep up the awesome work :)

[leebyron]

I definitely agree with you that we should be promoting higher quality documentation! That's really good feedback.

[hwillson]

Great discussion all. The site has gone through a few iterations since this issue was created, and has incorporated some of the feedback here. Since this issue is now over 6 years old, let's close it off and track new docs ideas in new issues. Thanks!