generator docs: asyncAPI Specification File

Description

Added documentation for the AsyncAPI specification file

Aug 03 '22 19:08 Florence-Njeri

@pratik2315 Let me know if I have some misleading information here. Thoughts, critics, and improvements are welcomed 😅

Aug 03 '22 19:08 Florence-Njeri

Hey @alequetzalli, @Annysah, @starlightknown, @nelsonmic, @thulieblack I have put up a PR for the specification file. I'll appreciate any feedback/criticism I get 😄

Aug 05 '22 20:08 Florence-Njeri

Hey @Florence-Njeri ! The docs look awesome✨ So far, all the technical stuff looks right! Here are some changes I would suggest:

The installation guide hyperlink is inactive. I think you left it open-ended on purpose since there is no installation.md file created yet😁 For now, what do you think, If we link the installation guide hyperlink to the index.md file which is going to have Generator Introduction🤔? Its general convention for installation steps to be a part of introduction itself. For example, Look at 1 and 2 these two examples. Let me know what do you think!
I think it would be awesome if you also hyperlink the template.md file in the beginning as well, just like you have mentioned parser.js. Since Template is also illustrated in your diagram along with the AsyncApi file. I think it would be awesome if we hyperlink the "template.md" concepts section. What do you think?🤔
I don't know how all these texts are going to look in the website when we migrate these docs from the github markdowns. You have written some awesome stuff in the "generation process" section. But IMHO right now, the information in the "generation process" paragraph could be conveyed in a better way if you split it between paragraphs/bullet points. Just like you have organized rest of the docs in this file. Right now, the information looks a bit hard to read for me but don't know I guess i might be a bit biased on this point😂 since I have shorter attention span and find it easy when the information is organized in shorter paragraphs🤣 Please ignore this point if it sounds wrong🤣

Aug 06 '22 17:08 pratik9315

Honestly, all the technical stuff looks correct to me for now. But since, I am relatively new to the generator tool, I might have missed some of the in-depth stuff. I think @magicmatatjahu @fmvilas could help you adding/removing any extra stuff and provide an accurate feedback on your docs😁

Aug 06 '22 17:08 pratik9315

@pratik2315 thank you for the detailed feedback and good catch on the link. On the third point, I agree, I'll try to break down that section and make it more readable. Thanks a bunch Pratik 😁

Aug 07 '22 17:08 Florence-Njeri

You know, I def enjoyed the content blocks you added the note and idea emojis! Since this PR brings up the topic of emoji use in Docs, I just wanted to highlight that we don't have a set Docs style guide to dictate emoji use yet. In the past, I think we've felt it would be ok to use informational emojis sparingly in appropriate sections, such as the examples you're adding here. I don't have anything against keeping the emojis you use here, but I just wanted to mention this in case someone else in the community also brings it up. ✌🏽

Btw, in the next draft iteration, we prob want to determine if you want to add one of our React components for the "remember" content blocks like we see in our quickstart, Getting Started... Screen Shot 2022-08-15 at 3 56 47 PM

Aug 15 '22 22:08 quetzalliwrites

@Florence-Njeri This is a high-quality technical content ❤️ You only went a bit far with it, as it is not only about the specification file. You actually also covered the intro which is not bad, just requires restructure.

So my suggestion:

apply fixes from @alequetzalli
in the same PR move some content from asyncapi-file.md to index.md

Details about what to move to index file:

it is all mainly about the diagram, it is great, but it is not only about the AsyncAPI file, it covers entire generator. So we start with it in the intro, but then use it a base to break it apart in other section.
I suggested some changes to the diagram, to include Template Context and Template Files. Btw did I say how happy I am that we choose Mermaid, and applying suggestions was so easy ❤️ -> have a look in live editor (notice how I'm using aliases to make sure we do not repeat the name of the component in the diagram to often)
here I propose a simplified diagram just for the asyncapi-file.md where you explain stuff only related to AsyncAPI file in Generator
from section What is the Asyncapi Specification? I think you only need to move this sentence (The specification file when fed as an input to the generator library via the asyncAPI CLI command, shown in the code snippet below, will generate API documentation or generate message-based API boilerplate code.) to the introduction, but it should also then mention not only how it looks like through CLI but also directly through library API
```
// Generator instance creation
const generator = new Generator('~/my-template', '~/output');
// Use instance of the generator to generate output from any AsyncAPI file
await generator.generateFromFile('~/asyncapi.yaml');
```
I'm not sure we need Use cases of the API definition file section. I was always thinking people, when reading docs for generator already know what are AsyncAPI use cases. So maybe it should rather change into use cases for generator, in the intro document?
In section The generation process you very well explain the whole process of generation. This is good for the intro document (just please rewrite the paragraph description into a numbered list to give structure to the text that will make it easier to follow, use "bold" on words that map to items from the diagram, so it is easier for the reader to map content to the diagram), and in asyncapi-file.md just focus on smaller diagram
I can help you later to add more content to Advantage of using the asyncApiDocument instead of the asyncapiString in your template to show case some examples, but yeah, not to much in one feedback. Same about method sections

@Florence-Njeri don't get discouraged by the amount of feedback, you did a great initial PR. I'm super happy to see how well you understand the generation process 👏🏼

Aug 17 '22 15:08 derberg

@derberg this is ready for the second review. I'd like an in-depth review of the rendering process in the index.md file incase I've missed something or the information there is incorrect

Aug 31 '22 17:08 Florence-Njeri

On a totally unrelated note, I came across this paragraph from one of the blogs while researching about the spec file :

The first two lines talk about how AsyncAPI playground is a helpful tool for getting familiar with the AsyncAPI spec file. Do you think a mention the Playground tool is necessary in context to specification file? or since we are talking about the Generator tool, jumping into other tools will cause a conflict🤔😅? Blog link cc: @derberg @Florence-Njeri

Sep 08 '22 17:09 pratik9315

On a totally unrelated note, I came across this paragraph from one of the blogs while researching about the spec file :

The first two lines talk about how AsyncAPI playground is a helpful tool for getting familiar with the AsyncAPI spec file. Do you think a mention the Playground tool is necessary in context to specification file? or since we are talking about the Generator tool, jumping into other tools will cause a conflict🤔😅? Blog link cc: @derberg @Florence-Njeri @pratik2315

I think this is now called Studio 😄

Sep 19 '22 18:09 quetzalliwrites

@pratik2315

The first two lines talk about how AsyncAPI playground is a helpful tool for getting familiar with the AsyncAPI spec file. Do you think a mention the Playground tool is necessary in context to specification file? or since we are talking about the Generator tool, jumping into other tools will cause a conflict🤔😅? Blog link

No strong opinion as long as it is just a note.

btw, it is not playground anymore but AsyncAPI Studio.

Sep 21 '22 14:09 derberg

@pratik2315

The first two lines talk about how AsyncAPI playground is a helpful tool for getting familiar with the AsyncAPI spec file. Do you think a mention the Playground tool is necessary in context to specification file? or since we are talking about the Generator tool, jumping into other tools will cause a conflict🤔😅? Blog link

No strong opinion as long as it is just a note.

btw, it is not playground anymore but AsyncAPI Studio.

I'll add it as a note

Sep 22 '22 12:09 Florence-Njeri

@derberg @alequetzalli I have implemented all the feedback, both editorial and technical, I received.

Sep 26 '22 15:09 Florence-Njeri

I will hold off on approval until we're ready to merge your installation & usage PRs together. :)

Sep 28 '22 00:09 quetzalliwrites

Kudos, SonarCloud Quality Gate passed!