Why? What? Who? How? (Tutorial) - Please Answer The Key Questions #1

nelsonic · 2020-07-16T12:46:10Z

Hi @th0mas, 👋
as noted in #7, #8 and #9, it would be really good to have a complete beginners guide to insomnia core in general
and then specifically how we are using it in our smart-home-security-system project 🏡

As with any new technology we adopt @dwyl, we need to have a beginner friendly intro explaining exactly what problem the tech/tool solves for us and why it's a total no-brainer to use it instead of anything else. We are very conscious/deliberate with our technology stack selection/adoption because we know each addition adds cognitive load, complexity and maintenance overhead. That being said we are stoked when people introduce us to new tools that can help make our lives easier. So ...

Please use this repository to write up everything you know about insomnia core so that someone who has never heard of it before can get started.
In the "How?" section, it's reasonably safe to assume they know what a REST API is (even if they have never built one themselves)
and that the have some familiarity with Elixir/Phoenix. But the tutorial is meant to show them everything they need to know from first principals so don't make any assumptions beyond "Todo List" level.

Why?

Describe why someone would want to use insomnia core for designing/documenting/managing a REST API.
Summarise the key benefits preferably in bullet points so people can quickly see that it's relevant to them.

We always start with why because it's the first question people ask themselves.
Within a handful of seconds of starting to read a page, people think: "What's in it for me?" (WIIFM)
Not because they are self-centred, just because they are busy and need to know fast if it's worth their time.
i.e. "Why should I bother with this when there are so many other things competing for my attention?"
So we need to answer that question ASAP in anything we write so people don't immediately bounce.

What?

In layperson's terms, what are the key features/benefits of insomnia over handrolling the API or using a different API creation/management tool? Again, use bullet points or a short paragraph.

Limitations?

At present insomnia does not support WebSockets Kong/insomnia#528 and there does not appear to be a timeline for it.
As noted in "Why Elixir" one of the biggest reasons we use Elixir/Phoenix is for Channels.
Can we still use insomnia for the REST API portion and then hand-craft the spec/docs for our Channels/RealTime API?

Who?

Answer the question: "Who is this tutorial for?"
(it's definitely not "everyone" ... but what subset of the dev community is it relevant to?)

How?

Show how to get started with insomina from scratch in a new project. (this repo)
Create a basic API step-by-step

If you're stuck for a basic example of a REST API to build with insomnia, just build out the endpoints of a Todo List which should already be familiar to the reader so it's less explaining.
Or, if you just want an ultra basic API with just an endpoint for GET and POST,
Consider the "Quotes" example we used in the https://github.com/dwyl/phoenix-content-negotiation-tutorial
Where the POST would be adding a new quote to the database.

Demonstrate the reader how insomnia makes creating/extending/maintaining the API easier.

tl;dr

Technical writing (written communication) is every bit as important as crafting code, read: nelsonic/nelsonic.github.io#797
So please take your time to write something that is a beginner-friendly as possible.
We have several examples you can follow e.g:

Once you're done, you could mirror the tutorial to your personal site as a "blog" post/tutorial.
When you applied to work with us this summer, we looked at your personal site as evidence of your proactiveness.
And specifically at your Fancy Lights "lockdown" project as a sign you could actually get work done. 🚀
The more content you can publish on your personal site the better for your long-term job/career goals.

The text was updated successfully, but these errors were encountered:

th0mas · 2020-07-16T14:57:48Z

I'll get on this tomorrow (Friday)

nelsonic · 2020-07-16T15:03:16Z

Thanks @th0mas you're a ⭐ !
(love what you've proactively done with learn-scenic so far; keep up the great work!) 🚀

iteles · 2020-07-16T15:16:41Z

@nelsonic On a slightly separate note, this description of the 'Why? What? Who? How?' format explanation would be really useful as a readme in our contributing repo! I can open an issue there.