docs: update the getting started docs page

[Annysah]

Description

• Updated the tutorial outline to be in sync with the given template.

Related issue(s)
Fixes #793

[netlify]

✅ Deploy Preview for asyncapi-website ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	f5f2cc3
🔍 Latest deploy log	https://app.netlify.com/sites/asyncapi-website/deploys/63291b5e50db940008b19035
😎 Deploy Preview	https://deploy-preview-825--asyncapi-website.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[github-actions]

Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[github-actions]

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🔴 Performance	27
🟢 Accessibility	95
🟠 Best practices	83
🟢 SEO	90
🔴 PWA	30

Lighthouse ran on https://deploy-preview-825--asyncapi-website.netlify.app/

[alequetzalli]

So this introduction needs to be an introduction to the tutorial, not the spec. 😸 Let's update this section to detail what this tutorial is going to teach us and what we are going to build.

⭐ For a tutorial introduction, you want to describe:

• what the user will build (list technologies and end goal)
• overview of main steps to build it
• what the user will learn

Let's go ahead and give this section another go 😃

[alequetzalli]

😸 For the Summary section in our tutorials, we are writing:

• a summary of what the user just built and what technologies were used (again)
• an explanation of what the user learned to do

A big part of improving this tutorial means both re-writing and adding new content ❤️ based on our new IA goals.

[alequetzalli]

Suggested change

	In order to successfully set up AsyncAPI, you'll need to download a few things:
	Before you proceed to the next stage, you'll need to download a few things:

[alequetzalli]

Suggested change

	Now that you've completed this tutorial, check out our [Streetlights](https://www.asyncapi.com/docs/tutorials/streetlights) tutorial to learn how to create a basic practical example of a system that can turn on and off streetlights with AsyncAPI.
	Now that you've completed this tutorial, check out our [Streetlights](https://www.asyncapi.com/docs/tutorials/streetlights) tutorial to learn how to create a sample IoT system that turns streetlights on and off with AsyncAPI.

[alequetzalli]

Good start @Annysah! 🎉🎉🎉

Let's go for Draft 2. ❤️

[Annysah]

Good start @Annysah! tadatadatada

Let's go for Draft 2. heart

Thanks Ale for the reviews, I will get to work!

[Annysah]

Hi @alequetzalli,

Just submitted the second draft.

[Annysah]

In addition to the requested changes, I added a section "Generating the docs".

Would it be a necessary addition?

[alequetzalli]

This is looking better, thank you so much for helping us update the outline of this tutorial to match our new IA work, @Annysah!

Let's first ask for a technical review from @derberg and if he doesn't have any feedback, then I will do a last round of editorial fixes for us :)

[derberg]

sure, I'll definitely have a look, but please first solve the merge conflicts, and then ping me again so I know it is ready for review (sometimes things get messy during solving conflicts, so better if i look after)

[Annysah]

sure, I'll definitely have a look, but please first solve the merge conflicts, and then ping me again so I know it is ready for review (sometimes things get messy during solving conflicts, so better if i look after)

Alright @derberg, I will work on resolving it.

Thank you!

[derberg]

Afaik the document that you edit here in this PR is https://www.asyncapi.com/docs/tutorials/getting-started and I'm not 100% sure we really want to turn it into a tutorial. I think this should be a kind of intro to getting started, so it is now.

now this document at the same time contains a general explanation of AsyncAPI goal (was there before) and some step-by-step explanation on how to create an AsyncAPI document + generate docs for it. Technically your instructions are very accurate but was it the goal. The Getting Started index document is on the upper level of all the getting started tutorials. If feels confusing that in upper level we create asyncapi file and generate docs, and then we create new asyncapi document again, with different protocol.

I'm not sure you know what I mean. I think the focus should go on these documents 👇🏼

to make sure there is a flow, that more AsyncAPI spec features (objects) are explained step by step, that examples (if possible) are based on the same app example, so they are consistent (not https://www.asyncapi.com/docs/tutorials/getting-started/asyncapi-documents is not consistent with the rest)

maybe let's go back to #793 and clarify the scope there? @alequetzalli thoughts?

[alequetzalli]

Afaik the document that you edit here in this PR is https://www.asyncapi.com/docs/tutorials/getting-started and I'm not 100% sure we really want to turn it into a tutorial. I think this should be a kind of intro to getting started, so it is now.

now this document at the same time contains a general explanation of AsyncAPI goal (was there before) and some step-by-step explanation on how to create an AsyncAPI document + generate docs for it. Technically your instructions are very accurate but was it the goal.

..........

@derberg Ok dude.... First, this is SO CONFUSING in the way you wrote it, you need to slow down and breathe before you reply to stuff. 😝 (just explaining cause you really confused poor @Annysah, so I am trying to help clarify to her what you said 😄✌🏽)

Second, Seeing what Anisat wrote in her 2nd draft here + thinking of your feedback Lukasz, I am inclined to agree that this Getting Started is really a quickstart, and not a tutorial. If yes, if we consider it a quickstart, that also means the TW outline is not going to be the same as the outline for a tutorial and thus does not need to change.

So IOW @Annysah, what Lukasz was expressing is that what you wrote/added in this PR is technically accurate, BUT potentially did not make sense to incorporate because his take was that this piece of TW content was not a tutorial. (Now you can see why I emphasized so much in the previous paragraph that I agreed this was a quickstart to the technology of AsyncAPI.)

Since a quickstart to the technology of AsyncAPI is a different kind of TW content, the goals and outline will be different than that which is needed for a tutorial that explains things you can do with the technology of AsyncAPI. 😀✌🏽

Lastly, what this means is that I don't think we actually need to merge this PR and it actually makes sense to close it, Anisat. 😀✌🏽 This doesn't mean you didn't do a GOOD job! I think it was pretty good and like Lukasz even himself said, what you added was technically correct. And that's always a good thing! haha 😎 Essentially, Lukasz was just seeing that this is one of those PRs that after the fact, you happen to realize is not the best idea to merge for a project. Not a big deal and it was still SUPER GOOD to have you practice writing and getting more familiar with AsyncAPI. 😀❤️

let me know if this makes sense now 😀 @Annysah! and I think it could be as simple as us closing this PR (unless lukasz had diff thoughts) and then we identify a new task for you (which there is! hahaha trust meee)

maybe let's go back to #793 and clarify the scope there? @alequetzalli thoughts?

No lukasz, the scope there is clear; it's a tutorial update with new outline template. I think you just got confused because you don't think of this as a tutorial. (which we agree on hahaa)

[derberg]

ups, sorry for being confusing. I actually did not rush with my comment, on a contrary, I tried to be as detailed as possible to express my confusion 😆 because the content, as I wrote, was technically accurate, but the location was confusing and I could not figure much from linked issue.

I think it is a good idea to have a kind of tutorial, that is super straightforward, just few steps, from creating a file to generating docs. Let's just first discuss the scope in an issue first, because for example I think it would be lovely to use AsyncAPI CLI for it, where you have the asyncapi new command and with one command you can actually create an AsyncAPI file from existing examples

[Annysah]

Thank you so much @alequetzalli for the clarifications. I think I now understand what @derberg means.

@derberg Thank you for the feedback as well!

[Annysah]

ups, sorry for being confusing. I actually did not rush with my comment, on a contrary, I tried to be as detailed as possible to express my confusion 😆 because the content, as I wrote, was technically accurate, but the location was confusing and I could not figure much from linked issue.

I think it is a good idea to have a kind of tutorial, that is super straightforward, just few steps, from creating a file to generating docs. Let's just first discuss the scope in an issue first, because for example I think it would be lovely to use AsyncAPI CLI for it, where you have the asyncapi new command and with one command you can actually create an AsyncAPI file from existing examples

Is the AsyncAPI CLI the same as the studio?

[derberg]

@Annysah CLI is something that you use in the terminal -> https://www.asyncapi.com/tools/cli

so for example after installing CLI, when you run asyncapi new --file-name=asyncapi.yml --example=default-example.yaml --no-tty in the terminal, the new AsyncAPI file is immediately generated for you

[Annysah]

So I was thinking in addition to creating a tutorial on how to get started with AsyncAPI using the CLI, we could also possibly restructure the outline of the "Getting Started" section.

Here is a link to a draft of an outline idea I worked on: https://hashnode.com/preview/62cffe97466c6ad9ff5d96c2

cc: @alequetzalli @derberg @starlightknown @nelsonmic @pratik2315 @Florence-Njeri @thulieblack

[alequetzalli]

So I was thinking in addition to creating a tutorial on how to get started with AsyncAPI using the CLI, we could also possibly restructure the outline of the "Getting Started" section.
Here is a link to a draft of an outline idea I worked on: https://hashnode.com/preview/62cffe97466c6ad9ff5d96c2

Oh lukaszzzz we especially wanted your thoughts on it! 😀

@derberg

[derberg]

I have some concerns with the outline, basically what we lose, and we had so far:

• we have https://www.asyncapi.com/docs/tutorials/getting-started/hello-world now, and I like it by it's super simple step-by-step approach when you highlight each section of AsyncAPI document and explain what it is. I do not see it in your Create an AsyncAPI Document, where you show the entire document end explain each part of it in one big paragraph. I prefer the approach from the current hello-world, or the other approach I used in the online workshop, where I add each section with additional explanations one by one. As this is for me a nature of a guide.
• Generate the Docs -> you propose to have a guide about docs generation but then there are more things users add to AsyncAPI document. At least this is how I understand the outline, that some basics first, then docs generation and then other AsyncAPI concepts (like security). I'm not 100% supporting this approach as docs generation is more "complex" (not by difficulty but flexibility) as there are more options to generate docs except for just ag command. So Generate the Docs would rather be an intro to a few other tutorials that explain how to do docs generation client side, server side, on a CI, react app, etc 😄 I assume your intention was to show the benefits to the user quickly. But we can do this by telling from the start that they should create a file in https://studio.asyncapi.com/ or VSCode with plugins or using CLI - what you already did. So maybe to make it more explicitly we should have it as part of instructions? like go to https://studio.asyncapi.com/ or install AsyncAPI CLI and run asyncapi open studio?

I love to see tutorials will not only be about writing AsyncAPI document but also how to convert it into docs ❤️
What is you proposal for Streetlights tutorial, as it kinda repeats Getting Started and then ends with code generation. I think it should also be mixed with new outline. So we have:

1. Write AsyncAPI document
2. Generate docs - new
3. Generate code - Streetlight tutorial modified

[alequetzalli]

It looks like we don't have sufficient reason to continue this one, so let's close this PR and leave our Quickstart as is. ✌🏽