Simpler getting started tutorial

[CharlesIrvineKC]

I'm just now delving into graphql-erlang and the graphql-erlang-tutorial. I'm very impressed with the depth and completeness of the tutorial. However, I really wish that I could start with a much simpler round trip tutorial to get a broad understanding of the concepts.

To be clear, this simpler tutorial should not include an explanation of cowboy, mnesia, graphql, Erlang, etc. It should be assumed that the reader is already familiar with these.

Just my humble opinions....

Thanks!!

[jlouis]

Hi!

Do you have any suggestions on how we could improve this? Maybe have a whirldwind tour of the core concepts as a chapter and a big START HERE if you happen to know most of the stuff in advance. Would something like that help you out as a reader?

There are a couple of changes which should flow into the tutorial, but maintenance of it takes a lot of time on our part because we have to go through and fixup what has changed. I'm currently aiming to support most of the Jun2018 specification update and then I plan on doing an update on the tutorial as well at the end of that work, since there are things which have changed in the specification which have some pretty big server implications (in particular, clients can now send null values as part of their input. This has full backwards compatibility on the client side, but it is going to change how servers act quite a lot).

[CharlesIrvineKC]

Hello,

Mostly, I would make the schema very simple. Something along the lines of https://www.howtographql.com/basics/2-core-concepts/ https://www.howtographql.com/basics/2-core-concepts/. Further, completely skip most intermediate and all advanced functionality in your initial presentation. You want to give your learners a high level understanding of the conceptual space before drilling down into anything advanced or significantly complex.

All just my humble opinion, of course. I will be digging into your documentation soon. Maybe you should wait until I’ve given it a serious effort before you spend any of your valuable time. I might find that once I get into things that I think its all pretty clear after all.

Thanks for what looks like a super product. I’m pretty excited about getting back into Erlang and learning about GraphQL.

Chuck

On Jun 26, 2018, at 5:03 AM, Jesper Louis Andersen [email protected] wrote:

Hi!

Do you have any suggestions on how we could improve this? Maybe have a whirldwind tour of the core concepts as a chapter and a big START HERE if you happen to know most of the stuff in advance. Would something like that help you out as a reader?

There are a couple of changes which should flow into the tutorial, but maintenance of it takes a lot of time on our part because we have to go through and fixup what has changed. I'm currently aiming to support most of the Jun2018 specification update and then I plan on doing an update on the tutorial as well at the end of that work, since there are things which have changed in the specification which have some pretty big server implications (in particular, clients can now send null values as part of their input. This has full backwards compatibility on the client side, but it is going to change how servers act quite a lot).

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/shopgun/graphql-erlang-tutorial/issues/59#issuecomment-400253256, or mute the thread https://github.com/notifications/unsubscribe-auth/AAoGarPpO2Hq6-hh0x--k6uLlthRmbkXks5uAgb7gaJpZM4U2Q7i.

[CharlesIrvineKC]

I reviewed GraphQL in general and took another pass at going through the tutorial. For me, I'm not finding the it as helpful as I would have hoped. I think it would be preferable to step users through each step from scratch, letting them enter or copy/paste code and invoke the necessary commands. I think the Star Wars example is way to complex for a first tutorial. Instead I would devise the simplest domain possible that permits exploration of the minimum but necessary concepts. I don't think you ought to try to explain anything other than just graphql-erlang, i.e. no explanation of cowboy, rebar3 or anything like that.

Here is a sample elixir tutorial: https://www.howtographql.com/graphql-elixir/1-getting-started/

I see at www.howtographql.com an invitation to have additional tutorial added. Perhaps one could be added for Erlang-graphql.

[tarrencev]

I agree with @ChuckIrvine. For example, a Hello World example that has a very simple query and doesn't depend on having a db setup ect. just returns a "Hello World" string at runtime