Getting started experience

[wtrocki]

Hi

I have been recommending graphql-tools as way to start but the documentation doesn't provide getting started experience. It should actually show how to use it with express-graphql (code snippets are not finished). Example app will be good as well.

[yaacovCR]

Hey, thanks for this comment -- we definitely want to make the "Getting Started..." experience as easy as possible. Where do you think people are getting stuck?

Right now, each package basically has a section within the online documentation describing what it does. For example makeExecutableSchema generates an executable schema from sdl and a resolvers map. Usage with express-graphql or Apollo Server is no different from usage of any executable schema with these servers.

As another example, stitchSchemas generates a gateway schema for presumably remote subschemas, but this schema should still be spun up using express-graphql or Apollo Server. stitchSchemas could definitely use an examples section showing how to do auth, caching, etc, but your comment seems broader than that.

More broadly, do you think that there needs to be a full example of how to organize a schema and resolvers?

[wtrocki]

I personally did not stuck. But example in readme is not finished. it needs express middleware exposed to be functional

[wtrocki]

Usage with express-graphql or Apollo Server is no different from usage of any executable schema with these servers.

We both know about it but having express example will allow me to recommend GraphQL tools for beginners. Now I need to say - hey you use GraphQL tools and then get some extra package and do X. But then they ask why I should use this tool and not GraphQL express example. There is little to be done for huge impact. I know the answers for this - we do not need to discuss what can be done - tick is that not everyone who opens this repo know GraphQL so well and repo is just failing to tell people what is the value by having begginer introduction

[wtrocki]

I usually tend to ignore it but this happened to me many times. Even dropping some sample example people can use to replicate issues and getting started wil be cool

[yaacovCR]

I agree that many more examples would be great!

Just so we are on the same page, could you confirm that you are talking about the main project README?

As far as I can tell on the README, it's actually worse than an incomplete example -- we don't have an example at all -- just a hyperlink to the express-graphql project.

Is that what you mean, that an example is basically missing?

Or is there another location with the beginnings of an example, that is not quite all the way there?

Thanks for clarifying!

[wtrocki]

Yep. Normally I would PR first but wasn't sure if this will be readme.md in repo or better to have example folder in repo and mention in in readme

[yaacovCR]

I think PR to readme with minimal example would be fabulous.

Would also be great to start examples folder with more examples

[ardatan]

We have an example here but we can promote it maybe?
https://www.graphql-tools.com/docs/server-setup