Create a tutorial

[th0mas]

• Setup insomnia
• Create a request
• Templating introduction
• Post request
• Using Tags
• Authentication Overview

[th0mas]

@nelsonic are you able to give this a quick once over for typos etc before merging?

[nelsonic]

@th0mas will read it through today after standup. 👀

[nelsonic]

Hi @th0mas,
This is a good effort towards explaining insomnia, 👍
however the "How?" section covers a Go Todo List Api. 🤷‍♂️
We don't use Go for anything and we don't plan to use it.
We use Elixir and we need our insomnia guide to be relevant to the language we use.

I can only apoligise if I didn't make it clear in the issue yesterday: #1
But we really need the insomnia tutorial to be relevant to what we are building. i.e. use Elixir/Phoenix:

If we are using insomnia for our https://github.com/dwyl/smart-home-auth-server
then our tutorial needs to help the person who is new to the project understand why/how insomnia is used within that context.

Our established Technology Stack is Elixir/Phoenix. If it's not possible to use Elixir with insomnia, then please make that clear in the README.md.

The last thing we want to do is introduce people to a brand new programming language while they are learning insomnia it adds too much complexity to the tutorial and ultimately isn't relevant to the context where we are using insomnia in "production". It actually ends up being more confusing than helpful.

It might be safe to assume that people at your Uni course know Go-lang, it's even reasonably safe to assume that I (Nelson) know it, but it's definitely not a safe assumption when it comes to the rest of the team/community. 😞

Just to re-iterate: in isolation an insomnia tutorial that features a new (to @dwyl) programming language is perfectly fine and you've done a good job of making it simple and approachable. But in context, where we are using insomnia with Elixir for the Smart Home Hub, it's not very useful for whoever wants to understand how to maintain the project(s) we are building.

Please don't scrap the Go work you've done, it might be relevant to the devs who use Go.
But please move it to a new folder called go-lang-example along with the instructions.

What we need from this tutorial is more:
"This is a super basic example showing how we are using insomnia in our Elixir project(s)"

[th0mas]

Insomnia is a HTTP API client that only interacts with remote servers (and by extension, programming languages) over HTTP.

For the purpose of the guide, I assumed no programming knowledge whatsoever, as its not needed to consume APIs through Insomnia, and Insomnia is purely a HTTP client.

I used Golang as it means we can ship a server to test against as a single executable for people that may not have programming knowledge. This means it's only one command (./server) to start a test API server, with no prior dependencies required.

If I had used Elixir - (which I still can), users would have had to download and install an Elixir toolchain, along with Phoenix and possibly PostgreSQL, for no benefit in learning how to use Insomnia.

I can also include a Phoenix Server, but this would not change anything about the tutorial itself, as the REST API would stay the same, the same way that writing a server in Go or Elixir does not change what web browser you use to access the server.

Hope this helps

[nelsonic]

Hi @th0mas, totally get that insomnia is an HTTP API Client. 👍
In this case it's interacting with a local server over HTTP.
And if the person wants to understand the server "under the hood", they need to read Go.
Go is very readable and I think we should keep the server you have created.
But it's definitely a "context switch" for someone who is not used to reading it.
I don't think it would "tax" anyone in our current team, it's not exactly complex.
But I've seen people who are learning get stuck and unable to make progress over smaller barriers.
So I'm always conscious of minimising the barriers wherever possible.
Maybe I shouldn't care as much about people getting stuck ...
But as a self-taught coder (for the most part alone) I know how frustrating it can be.
Anyway, the point isn't the Go code you have written, which is readable, it's the principal of reducing obstacles to learning wherever possible. And contextualising things in terms of where we are using it. If someone wants to understand the HTTP server and they already know Elixir, it's going to be much faster if the HTTP server is in the language they know. 💭

What I was saying in the issue was that they already have Elixir installed.
Assume that the person reading the learn-insomnia is maintaining the code you have written for the firmware, they are in the Elixir mindset already and just need to grok what this "insomnia" thing is so they can get back to maintaining the firmware.

100% agree we definitely don't need a full-on Phoenix Server with Postgres. 👍
Luckily a plug-based web App/API can be written very simply in Elixir.
e.g. https://github.com/dwyl/elixir-plug-tutorial/blob/master/lib/app/router.ex
just in-line the router handlers in the router.ex file and you're off to the races.
Not saying Elixir is better than Go by any stretch.
But when I see a Binary executable being added to a Git Repo, I shudder:

It's generally undesirable to store blobs of compiled code in Git.
Even if in this case it actually makes sense from a usability perspective;
having the /server/server executable makes it a "black box".
It's just not a precedent you want to set because beginners will think it's "OK" to do it.

Completely understand that the tutorial itself won't change with an Elixir web server.
In fact that's exactly what we want! We want the tutorial to be language "agnostic".
But if the person wants to understand the code in the server, we don't want them to have to go googling for things.

Thanks.

[th0mas]

@nelsonic Just pushed some changes to add a test admin route on Elixir, might need to git pull on your end to finish the tutorial 👍

[nelsonic]

@th0mas thanks for adding the Elixir Server.
100% agree that for this simple Example the Go is much friendlier for people who don't have much experience of Elixir (or other languages). 👍
I've added a few extra screenshots while following the tutorial. (and fixed a couple of typos)
But your original content is solid.
Thanks. 🙌