search

graphile / crystal

🔮 Graphile's Crystal Monorepo; home to Grafast, PostGraphile, pg-introspection, pg-sql2 and much more!
https://graphile.org/
Other
12.62k stars 571 forks source link

Suggestion: add a TL;DR to the quickstart guide #2203

Open baj1210 opened 1 month ago

baj1210 commented 1 month ago

Just a suggestion:

Considering the differences between version 4 and next, it might benefit users if the docs could contain an installation section that just covers how to install postgraphile (or beta) and the plugins and maybe an example script showing how to deploy it with node.

Thanks for your efforts

benjie commented 1 month ago

Hi @baj1210; I think all of the usage pages cover installation; e.g. https://postgraphile.org/postgraphile/next/usage-cli and we also have a quickstart guide that talks about everything you need: https://postgraphile.org/postgraphile/next/quick-start-guide and various deployment docs, e.g. https://postgraphile.org/postgraphile/next/deploying-heroku

Where are you seeing the lack of documentation / where would you introduce this suggested content?

baj1210 commented 1 month ago

Hi Benjie, sorry for the delayed response. I guess I was hoping for maybe just a code block that could show the appropriate commands to run to get the latest postgraphile version (or earlier stable version) and some of the plugins needed to at least start with the command line execution. There's no lack of documentation at all, I was just inspired by laziness to see if you might be able to add the commands to install postgraphile (beta and stable) and the plugins needed for subscriptions functionality for those of us who enjoy blindly copying and pasting commands into their terminal without reading anything and then hoping for the best.

Perhaps something like:

` yard add postgraphile --save

or

npm install postgraphile --save

then perhaps a few essential plugins (if needed to be installed) `

Just a couple commands that can help users looking to install postgraphile locally on their machine so they can explore what it can do. It wouldn't need to be very long or detailed.

I would maybe add a TLDR; block of commands. I'd stick it right at the top of your very detailed docs.

image

benjie commented 1 month ago

@jemgillam Please consider adding a TL;DR in the proposed location. We should probably use the pgl command since that's the streamlined approach that doesn't require installing additional dependencies. Also maybe we should add a pgl-amber that's effectively an alias for pgl -P pgl/amber.