graphql-go
graphql-go copied to clipboard
graph-gophers
Documentation
I can see that the project is rather easy to understand and use. Coupled with the examples, one can understand how to implement this project.
However, I think it would be better if there was a more detailed README, or separate documentation. A way for someone to properly get started and implement basic features.
I think this is good because even the example projects don't have a proper README. One would have to dive into the code to see how it was implemented.
I would be happy to contribute to fixing this if others think it is necessary too. I'd also need input on what exactly should be in the README.
For example, which functionality needs better docs? The star wars provided is a pretty good example. I mean you could provide a readme detailing it step by step but it would still be parsing through code snippets.
Or are you talking about internal readmes the internal/ folder, because I do think there can be WAY better docs for the AST and parser
This is the entire readme of the star wars project.
What I'm saying is that someone needs to dig into code to understand exactly how to get started.
This could be made a lot easier with a good readme. Look at this project for example
I kinda agree, gonna do a PR for this, I'll link it back in this thread when it's shaping up for feedback
@stephenafamo and @aaahrens
I agree with you guys and any help on this would be highly appreciated. I don't want a super bloated README but we might add documentation (or better README) to each example. For now, we have only the starwars example but I would like to add at least two more - one hello-world and one for subscriptions once @matiasanaya's PR gets merged. Also, for some things we need to consider adding godoc examples.
@aaahrens If I may ask, is this still in the making? I could do a PR if necessary.
@smithaitufe Thanks for offering help. Any RPs would be highly appreciated. However as @aaahrens has asked above - what do you think needs documenting? Maybe we can list/discuss some ideas first before dedicating your time on a PR. Once the ideas are discussed and you have a clear goal - a PR would be more than welcome.
I think it would be helpful to also have a basic example that uses https://github.com/graph-gophers/dataloader since GraphQL really should be set up with dataloaders.
@fedorareis there are already basic examples in that project https://github.com/graph-gophers/dataloader/tree/master/example
@pavelnikolov I was thinking more along the lines of how they work with resolvers. I've already looked at the examples you referenced and while I am still trying to fully understand the examples I feel like the larger issue I am having with the examples is figuring out how it ties into GraphQL.
I've been doing a lot of looking at https://github.com/OscarYuen/go-graphql-starter and https://github.com/tonyghita/graphql-go-example and https://github.com/graph-gophers/graphql-go/tree/master/example/starwars to try to figure out how to build out a production GraphQL API, but I feel like even with all of those the lack of documentation or comments has made it hard to fully understand what is going on and why things are set up the way they are.
There are a lot of useful bits of information scattered throughout the issues for this repo, from CORS, to handlers, to other bits of info and advice
I'm not sure what I think the solution is, but because there seems to be a smaller community that uses this project there are fewer resources to help people get up to speed with using this project well.
@fedorareis Thanks for the comment : ) Recently I am still busy on working the company project. As there would be lots of changes, I would try to revamp the example project and the README asap 👯♂️
Closing this due to inactivity. I'm also adding a lot of executable examples and improving documentation in the next release.