Improve Lackluster Documentation

[kitsunekyo]

Documentation

i've so far seen quite a lot of questions revolving around documentation, specific to the graphql-js implementation and how to translate graphql schemas to the graphql-types.

• the onepager on https://graphql.org/graphql-js/ does not even use GraphQLObjectType, or GraphQLSchema to define schemas but uses a template string instead.
• the class GraphQLDirective is not even mentioned in the API Reference, which is extremely confusing when trying to wrap your head around how to use graphql properly with graphql-js.

i'm not experienced enought to create a pull request for this, but I think the javascript community would greatly benefit from better documentation on how the javascript specific implementation works with graphql.

and since the graphql-js package already exists, it makes no sense to just omit the documentation

#446 #811 #799

[leebyron]

Totally agree. Adding and improving documentation is the most valuable thing a new contributor can do. Writing documentation for some part of the library is also a great way to learn that area and gain expertise

[someoneinatree]

Would happily contribute to improve this, is my current sticking point coming back to gql after a long break, but not even sure I know how to do it "right". Does anyone know where the relevant info currently is, and what format it should be in?

[leebyron]

For API-level documentation, I would love to see an automated tool which extracts flow types and comments to produce good documentation. The biggest issue with API docs is keeping them in sync with code. Having the docs live in the code solves this problem and makes the code easier to read. Any contributors who want to take this on will have my support and respect.

A slightly less ambitious but still highly impactful effort would be to move the docs into this repo. Right now they are part of the graphql.org repo and that doesn’t make any sense and makes keeping them up to date all the more cumbersome.

[AdamT213]

Not sure if anyone is currently working on the above but I'd be down to work on

A slightly less ambitious but still highly impactful effort would be to move the docs into this repo. Right now they are part of the graphql.org repo and that doesn’t make any sense and makes keeping them up to date all the more cumbersome.

that

[IvanGoncharov]

@AdamT213 Thank you for volunteering 👍
ATM graphql.org is in a process of migrating from FB to Linux Foundation so it's better to postpone this task until this process is finished.

[AdamT213]

Makes sense. I'll keep an eye out for when the issue starts getting some action again.

[skywickenden]

The docs have now been copied across and are available in the docs folder. #1923 Thanks @IvanGoncharov

These are still as they were on https://graphql.org/learn/ with the schema in a template string, but it is a start.