search

ChilliCream / graphql-platform

Welcome to the home of the Hot Chocolate GraphQL server for .NET, the Strawberry Shake GraphQL client for .NET and Banana Cake Pop the awesome Monaco based GraphQL IDE.
https://chillicream.com
MIT License
5.22k stars 743 forks source link

More Accessible "Getting Started" page #2289

Closed jacknugent closed 2 years ago

jacknugent commented 4 years ago

Is your feature request related to a problem? Please describe. I was frustrated at how long it took me to "Get Started" with this project; I think in its current form, any user with no experience with HotChocolate will waste a lot of time on the README and Introduction. The instructions for setup could be much more clear.

Right now, the example project at the very beginning of the README.md requires a brand new user to already know that they have to visit https://localhost:5001/graphql/playground/ to write a GRAPHQL query. That omission alone from the "Getting Started" will waste a huge chunk of time for a new user.

This first section of the README also bombards a first-time user with links to GraphQL.org, the Facebook GraphQL repository, the slack channel, and the core documentation. A brand new user should not need to join the slack or read other project's documentation to get a "Hello World" app running.

Compare those instructions with something like GatsbyJS, which has an excellent Get Up and Running in 5 Minutes section that anybody can follow with ease.

Describe the solution you'd like I think "Getting Started" needs different language to improve the experience for a first-time visitor of this project.

  1. The starwars example should include instructions for running the app and visiting the right URL, along with an example Query to run.
  2. There could also be a "Get Up and Running" before the stars wars example that allows the user to implement the "code-first approach" without getting into any details. That way, a first-time user can be wooed by how easy HotChocolate actually is to set up!

I am open to suggestions and am happy to help resolve this issue if it's deemed helpful.

damikun commented 4 years ago

Hi @jacknugent sorry for that it was hard for you to start.. Currently all guys are focused on version 11. Version 11 will have new DOCs because of changes in API.. I agree that main .md can be updated and that`s time for us in community to help with this..

Current startup part can be overwritten from Michaels GQL workshop where he have detailed step-by-step tutorial included texts.. Adding hire one of his examples... You can find it hire: https://github.com/michaelstaib/graphql-workshop/blob/master/docs/1-creating-a-graphql-server-project.md

For V11 they also preparing some video content etc.. And what i hear also will be on Microsoft channel 9...

But all this take time and guys are focused on code for now..

All parts of WebDOC or Github are forkable an anybody can contribute to it after check it gets merged...

jacknugent commented 4 years ago

Yes, that example is great, thank you! Would love for an example like that one to have more visibility after Version 11.

michaelstaib commented 4 years ago

We are working on a new website ... at the moment we are working our way through the backlog and will start on documentation probably at the end of September/mid-October.

damikun commented 2 years ago

I think this can be closed since new web as quite good documentation how to start-up...