Lighthouse: improve documentation

Created on 13 Jul 2018 · 6Comments · Source: nuwave/lighthouse

thanx so dam much for this package, having the same schema syntax in both front & end is just heaven 😍.

still could someone pleaaaaaaaaaaaaaase for the love of god, do something with the documentation ?

i have to keep at least 10 tabs opened from "examples, issues, the official doc, the src files" just to understand how things works 😭.

Source

ctf0

Most helpful comment

things like

how to create custom directives

for those who are used to REST, how would u transform ur code from route&controller, to query/mutation while using the same logic "with some minor changes if needed", after all that would be the main reason why u would use this package over the other like https://github.com/Folkloreatelier/laravel-graphql which its api is basically like building a rocket
instead of using the full class namespace for each resolver, apparently we can use namespaces in @group "which i found by pure luck"
atm the package doesnt work with lumen, because some parts are tightly coupled to laravel, having a better docs should make it easier for anyone to use the same base code from the package while custom adding its own implementation, this way u r free to use laravel auth/passport/jwt/3rd party/etc... & u dont need to clone a whole project https://github.com/kikoseijo/lumen-lighthouse-graphql just to get ur code to work. "if you care more about adding new features than writing docs for it, then maybe u should turn the package to a full app"
i know that the package is built on another logic which the user should be familiar with first, but it wont hurt if the docs have some tips around usage to make it more enjoyable for everyone to learn this new syntax.
for input validation, i know we have @validate directive but atm u either use the array syntax or create a validator class, why not have a helper which we can use inside the resolver so the logic would be as close as possible to the original validator https://laravel.com/docs/5.5/validation#quick-writing-the-validation-logic

i wish i have more suggestions for u but so far after already 3 days digging my way in am still lost, so for now thats what i can think of.

as for how i can help with the docs, as a first step i honestly was thinking of just moving all the directives to the sidebar, this way you dont have to go back & forth between all the items to find what u r after, maybe add a search functionality as well.

ctf0 on 13 Jul 2018

👍2

All 6 comments

Thanks for the praise, we hope to deliver the best dev experience possible with the library.

I do agree that the documentation can be a bit spotty in parts. So, i invite you to contribute your findings to https://github.com/nuwave/lighthouse-docs

The docs are open source and free for everyone to improve!

spawnia on 13 Jul 2018

the problem is am still learning it, and the docs in its current form is a big wall in front of anyone wants to get involved.

i believe the more experienced/veteran users like you would do much more than a newbie like myself + it would avoid tickets like https://github.com/nuwave/lighthouse/issues/106

ctf0 on 13 Jul 2018

👍1

I would love to hear some concrete suggestions on what we can put in the docs to make it easier.

What parts in particular where hard for you? What information did aid you in understanding?

spawnia on 13 Jul 2018

things like

how to create custom directives

for those who are used to REST, how would u transform ur code from route&controller, to query/mutation while using the same logic "with some minor changes if needed", after all that would be the main reason why u would use this package over the other like https://github.com/Folkloreatelier/laravel-graphql which its api is basically like building a rocket
instead of using the full class namespace for each resolver, apparently we can use namespaces in @group "which i found by pure luck"
atm the package doesnt work with lumen, because some parts are tightly coupled to laravel, having a better docs should make it easier for anyone to use the same base code from the package while custom adding its own implementation, this way u r free to use laravel auth/passport/jwt/3rd party/etc... & u dont need to clone a whole project https://github.com/kikoseijo/lumen-lighthouse-graphql just to get ur code to work. "if you care more about adding new features than writing docs for it, then maybe u should turn the package to a full app"
i know that the package is built on another logic which the user should be familiar with first, but it wont hurt if the docs have some tips around usage to make it more enjoyable for everyone to learn this new syntax.
for input validation, i know we have @validate directive but atm u either use the array syntax or create a validator class, why not have a helper which we can use inside the resolver so the logic would be as close as possible to the original validator https://laravel.com/docs/5.5/validation#quick-writing-the-validation-logic