Graphiql: Better developer documentation

[rherrmann]

After cloning this repository and changing directory to packages/examples/graphiql-webpack/ and running npm run demo-build, the build fails with

Error: Cannot find module '@babel/core'
     babel-loader@8 requires Babel 7.x (the package '@babel/core'). If you'd like to use Babel 6.x ('babel-core'), you should install 'babel-loader@7'.

Adding @babel/core (currently version 7.7.4) to devDependencies solved the problem for me. Let me know if you want me to create a PR with this change.

[acao]

hey thanks for looking! did you ‘yarn’ at the workspace root first? i cant reproduce this even when removing node modules. this package is already present as a dev dependency, so it seems our issue is that i need to improve the demo documentation so you know the proper steps to take. for now youll want to just follow the netlify config

the other thing to note is that until a few more PRs are reviewed and merged we wont be publishing the tree shaking/bundler module resolution fix, so the webpack demo only reflects what’s in master, thus you’ll need the old webpack define plugin config hack for what’s currently published as 0.16.0

[rherrmann]

Thanks for clarifying. I didn't notice that 'yarn' is the build tool of choice. Certainly, for uninitiated people like me, a readme that explains how to build the examples would help.

Feel free to close the issue.

[acao]

@rherrmann if you don't mind, I'll keep this open and re-prioritize it as a documentation issue. we definately need some better documentation for developers! we have a CONTRIBUTING.md, but it does not contain enough information, nor does the README.md reference that I think? Either way, we could do for some improvements. Thanks for accidentally bringing some light to this issue!

[toolbear]

First off, thank you for graphiql. I found it functional, useful, and lightweight once I got over the hurdle of setup. Some feedback on that hurdle.

It may be useful to identify the developer personas and keep them in mind when revising the documentation and decided what steps each must take. Strawman:

• Persona A: wants a vanilla, static file GraphQL to drop into their website and point at their GraphQL endpoint
• Persona B: building their own IDE, wants to reuse graphiql components
• Persona C: wants to contribute to the graphiql codebase itself

I'm in the Persona A bucket. The first time (a few months back) I tried to get started, I remember having difficulty. I've since forgotten the steps I took to generate static files that I could drop onto my HTTP server (after a small hand-edit of the /graphql endpoint). Today I wanted to pick up the latest changes and find that I cannot reproduce this task and the documentation is of little help.

The docs seemed to be geared for personas B or C. For example, the "Getting Started" section of the README doesn't really describe how to get started (for any persona), but seems to be cataloging of commands:

1. `yarn` - install and link all packages
2. `yarn build` - cleans first, then builds everything but webpack bundles - `tsc --build`, `babel` etc
3. `yarn build-bundles` - builds webpack bundles that are used for releases
4. `yarn build-demo` - builds demo projects for netlify; we run this on CI to make sure webpack can consume our project in a standalone project.
5. `yarn test` - runs all of the above alongside linting and checks, jest mocha Cypress etc.
6. `yarn format` - autoformats with eslint --fix and prettier
7. `yarn lint` - checks for linting issues
8. `yarn e2e` - runs cypress headlessly against the minified bundle and a local schema server, like in CI.
9. `yarn jest` - runs global jest commands across the entire monorepo; try `yarn jest --watch` or `yarn jest DocExplorer` for example :D

Presumably each persona only needs to use a subset of those commands.

An actual recipe of steps to follow for each use case would be better.

A later command reference section could detail each command. Or instead, improve the self-documentation of running yarn help and yarn run (without a subcommand). Then if you want it in the README you can copy-paste it as a code block (or just suggest getting the command docs from the CLI).

This breadcrumb doesn't really provide additional info for getting started:

Learn more in [`CONTRIBUTING.md`](./CONTRIBUTING.md) documentation.

It would be useful to move documentation and steps geared for Persona C under CONTRIBUTING.md.

Within README.md a "Quickstart" section could address the needs of Persona A, going more in depth in later sections for personas B & C (with the breadcrumb to CONTRIBUTING for Persona C)

[acao]

@toolbear thanks for the feedback! this is all very helpful. there is another pass at CONTRIBUTING.MD planned soon already. A lot of things are still greatly in flux, and once there's a few more tooling changes I will be updating them again. It would be nice to make readme changes with every tooling change, but there have been quite a few, though I think the top-level commands are mostly stable for now. For example, we are in the midst of converting a lot of code from flow to typescript, so the build tooling is in a lot of flux.

Did you get a chance to read the GraphiQL readme at packages/graphiql/README.md? I think it addresses a lot of the questions you might have had. I think two of the three personas are represented there for contributing to GraphiQL? If not then thats another set of docs we need to improve even more, after the most recent overhaul that had a few reviews. It's really hard to document and orient people through a repo thats designed for building so many tools, such as vscode and other IDE extensions, in addition to building tools like GraphiQL, or re-using GraphiQL. So in reality there are really 6-8 different personas when people are visiting GraphiQL monorepo. We have petitioned to change the name of the repo to ide to make it more clear, but haven't been able to.

I'm sorry the new docs were so difficult for you! was it not clear that the getting started section for GraphiQL itself was linked from the main Readme.md? Or the examples that we linked to, were those helpful?

If you ever have any issues with the documentation again, you can always ask in our discord and I or others can usually answer within a few hours at most if not within a few minutes. Thanks for taking the time to review the documentation, and I'll make a few more passes at improving them!

[toolbear]

For reference, here's what didn't work for me this time around. And I'm not even certain that the end result had it worked would be some static files I could drop into my HTTP server. The CDN example works, but not for my use-case as I'd like to make small changes (like switching the /graphql endpoint).

git clone ...
cd graphiql
yarn
yarn build
cd examples/graphiql-webpack

yarn serve
# Error: Cannot find module 'command-line-args'
# ...

yarn create-react-app # from examples/graphiql-webpack/README.md
# error Command "create-react-app" not found.

yarn run create-react-app
# error Command "create-react-app" not found.

yarn run start
# same failure as `yarn serve`

yarn run build-demo
# ERROR in ./index.jsx
# Module not found: Error: Can't resolve 'graphiql/graphiql.css' in '/Users/toolbear/src/netflix/PDT/graphiql/examples/graphiql-webpack/src'
# @ ./index.jsx 8:0-31

[acao]

huh, what OS are you using? I watched my buddy set it up on OSX the other day just fine clean with similar commands, but we are still working on windows support for development.

CDN example allows custom urls, auth, custom headers, etc, what do you need to do? find me on discord https://discord.gg/hRpMAj

[acao]

either way I'm terribly sorry @toolbear that looks like a terrible developer experience. thanks again for taking the time to report this though.

also do you want to try a yarn --force from the root for me? is there a yarn.lock file diff? are you on the latest branch? do you have any package-lock.json files in your tree?

[acao]

also, we do confirm the webpack demo on every build at least in terms of just doing a straight build, however we dont test serve in CI. going to stage this work and try a clean build now

[acao]

if you want to try and reset everything, this should work:

yarn --force && yarn build && yarn build-bundles and then try graphiql-webpack?

[toolbear]

Did you get a chance to read the GraphiQL readme at packages/graphiql/README.md?

I started from the root README.md and missed the link to the packages/graphiql/README.md. I followed the "examples" link instead and read examples/graphiql-webpack/README.md instead.

either way I'm terribly sorry @toolbear ...

Apology appreciated, but unnecessary. I understand the challenges that come with supporting an OSS project.

Your assistance is appreciated.

are you on the latest branch? do you have any package-lock.json files in your tree?

I'm on master at commit cb7c68906a712ec2a582aa6ee903d02a8de20016.

Today I started by pulling in latest changes and run git clean -fxd to start from scratch. I'll give yarn --force at root a try.

do you have any package-lock.json files in your tree?

Yes.

However, I ran git clean -fxd before replying to this issue and that removes all the lock files, node_modules, etc. and should be as clean a slate as a fresh clone.

$ find . -name 'package-lock.json'
./node_modules/babel-polyfill/package-lock.json
./node_modules/babel-runtime/package-lock.json
./node_modules/fsevents/node_modules/needle/package-lock.json
./node_modules/rst-selector-parser/package-lock.json
./examples/graphiql-webpack/node_modules/fsevents/node_modules/npm-normalize-package-bin/package-lock.json
./examples/graphiql-webpack/package-lock.json

$ git clean -fxd
...

$ find . -name 'package-lock.json'
# no matches

if you want to try and reset everything...

Trying now.

[acao]

ok very helpful all of this! good to know that you missed the GraphiQL setup link, I need to make that super clear. Also should probably bury that list of commands in Contributing.md like you suggested.

that git clean -fxd looks real handy i'm gonna have to steal that, haha!
(follow up: opes, even though i knew what that command would do, i still managed to delete the issue templates i was working on, now i get to write better ones!)

[toolbear]

Success!

git clean -fxd
yarn --force && yarn build && yarn build-bundles
cd examples/graphiql-webpack
yarn run build-demo
cp dist/{index.html,main.js} $my_static_server/public/graphiql/

This was user error. I remember running yarn build-bundles per the docs, but at some point I think I started over (with git clean ...) and didn't rerun yarn build-bundles before trying to build the webpack example.

I'm good to go. Thanks for being so responsive.

that git clean -fxd looks real handy... even though i knew what that command would do, i still managed to delete the issue templates i was working on...

Oops 😅

In my day-to-day I actually use git clean -ixd for the interactive version that lets me exclude certain patterns from removal.

[acao]

also create-react-app is not meant to be executed there, my bad, i guess its confusing putting the sandbox example in the readme, but the sandbox is the CRA example. i should just put it in a seperate example that just a readme

[acao]

@toolbear hooray! glad it worked! i'm willing to bet its all the rolling dependabot updates and tooling changes over the past few months, feel like it leads to more dependency smell so that you practically need to yarn --force with every pull.

anyways again thanks so much @toolbear, this was all super helpful for learning where the gaps are in the docs, and how we can navigate people better to where they need to be. your advice of thinking persona-first is excellent, will help me structure the docs much better I hope. so many improvements to make to this repo, but docs improvements are some of the most important!

[toolbear]

This was user error.

Two user errors, actually:

1. Missing the link to packages/graphiql/README.md
2. omitting yarn build-bundles after attempting a reset

In hindsight, part of what tripped me up for (1) was quickly scanning the README and not noticing that the project is structured as a monorepo. I had the mental model of the root README "Getting Started" being all there was to the getting started documentation. After that didn't work, I set about trying to figure it out by looking through the examples directory.

[acao]

oh ok, I scanned your comment it looks like 😆 ! let me know if you need anything more, I'll keep this open until I clean up the contributing docs though for sure!

[toolbear]

Lastly, kudos again for this project.

In my view, GraphiQL is a huge contributor to graphql adoption in the industry and here at Netflix. I'm working on shipping a graphql endpoint for Netflix/hollow datastores. Being able to ship a query UI & IDE alongside it is so useful.

It has already given me agility while developing the endpoint. Not only do I think users will appreciate having GraphiQL, but I think it's an expectation now. Several other services here are already in PROD with vanilla/reference GraphiQL UIs deployed.

[acao]

@toolbear thank you thats a great honor to hear that! that's exactly why I'm so passionate about GraphiQL, because of how it can rapidly accelerate adoption of and comprehension of GraphQL and the schemas themselves. we have some really exciting things in store!