OSS Community Research: Survey to determine which tutorials are most needed by users

[starlightknown]

If you are a developer/architect/engineer on a team working to document AsyncAPI or a user who uses (wants to use) AsyncAPI to build something awesome, please help us by sharing your feedback about the tutorials you would like to see on the AsyncAPI website.

❔ Why do we need this survey?
Currently, AsyncAPI has two tutorials which are Streetlights and Streetlights - Interactive
We are working on making more tutorials that will help our users in the future.

📝 Questions

• Are you facing difficulties/challenges while using AsyncAPI? If yes, please specify
• Are you unfamiliar with EDA and AsyncAPI? If so, please tell us what tutorials you'd like to see from a beginner's perspective.
• What else can be done to improve the current tutorials, such as Streetlights?

💭 How can I participate?
You can help by providing valuable feedback here, or if you are someone who can assist us in creating these tutorials please create an issue regarding it, we are always looking for contributors.

[quetzalliwrites]

My suggestions:

• Describing Kafka with AsyncAPI: Learn how to document the API for your Kafka event sources by creating AsyncAPI documents.
• Creating AsyncAPI documents with WebSocket API: Learn how to create a complex AsyncAPI document using WebSocket API as an example.

[derberg]

I would only clarify the title as Creating AsyncAPI documents for WebSocket API

and also that it would be a set of tutorials, where you explain what WebSocket is, why AsyncAPI is a good fit for it, and then of course the work on tutorial that describes how to describe WebSocket API with AsyncAPI. At the end show some code generation.

here is some input for that https://www.asyncapi.com/blog?tags=WebSocket

---

as for Kafka, you definitely need to talk to @dalelane who provided already a lot of content for it. There are articles, and video about it that can serve as an excellent input.

[akshatnema]

My suggestion is regarding the Streetlights tutorial (Interactive) as some of the browsers do not support Katacoda.com and their tutorials. And also, I came up with this news https://www.oreilly.com/online-learning/leveraging-katacoda-technology.html that Katacoda is shutting down its services within 20 days. So, we should think to make our present tutorials on other platforms also. The smart Lightning application is the basic AsyncAPI tutorial that can help beginner users to understand it and this tutorial can be taken as an introduction to AsyncAPI for all the newcomers to AsyncAPI.

Regarding moving to other platforms, my suggestion will be to use Glitch or Replit or any other good platforms (if anyone knows) for the creation of new tutorials as well.

[quetzalliwrites]

@akshatnema The purpose of the survey is to identify new tutorials to add, not comment on improvements for existing tutorials.

Please stick to the topic of the thread so that we can provide useful suggestions. Otherwise you are only changing the topic and not helping the community user survey.

[akshatnema]

@alequetzalli Yeah I perfectly understand the concern we are targeting in this discussion. I'm targeting the issue that if we are going to again stick to Katacoda to make our tutorials, we may lose the hard work put in by so many people. Just to make aware about it that presently, some of the users are facing the problem to use Katacoda in the browser and pointing out the news regarding it, which was mentioned in the Slack general channel as well.

Sorry for getting off-topic about the discussion but my motive is to make you and the community aware of this.

[derberg]

Thanks @akshatnema. No matter if we use interactiveness with Katacoda or not, or even if we do not do it at all - this should not affect the list of tutorials that we need to provide to the users. Basically, technology should not block the delivery 😄

feel free to join asyncapi/website#125 or open a separate discussion if you want to help with this topic. I'm afraid that the crypto world unfortunately made things a bit more difficult 😞

[derberg]

we need tutorials on:

• how to validate AsyncAPI files
• how to extend validation with additional linting/governance with Spectral
• how to render documentation for AsyncAPI
• we need to extend the current tutorials list where we walk user through all the AsyncAPI features, not just Servers and Security an that is it. So for example have tutorial about adding a payload with schema like Avro and not default AsyncAPI Schema.

[derberg]

Some more content proposal. So what we have under getting started tutorials is:

• Event-Driven Architectures - intro to EDA
• Coming from OpenAPI - intro to AsyncAPI
• Hello world - extra simple example
• AsyncAPI documents - intro to format of AsyncAPI files
• Servers - how to add server info to AsyncAPI
• Adding security - how to add security to AsyncAPI

We are missing a lot 😅 Below is what we need. It is existing docs mixed with the ones I propose:

• new proposed docs are in bold
• doc titles are just proposals, subject for change
• might be that when we go deeper into every doc to clarify the scope, some docs might be split in 2

New navigation

• Event-Driven Architectures
• Coming from OpenAPI
• Hello world
• AsyncAPI documents
• AsyncAPI structure - intro to all root elements, short explanation of info, servers, channels, components and their purpose
• Servers
• Adding security
• Adding variables to URL - explain how to add variables to server URL when there are parts of URL that maybe different per runtime. And explain how these can be reused between 2 servers using components.serverVariables
• Adding channel - explain purpose of channels, different names for it, what people should put here (some overlap with channel concept doc probably). Add simple channel there, and explain how it related to server, that if you specify a channel and server, it is expected that given channel is present on all servers, and explain that channel can also specify that it is present only on server A or server B
• Specifing dynamic parts of channel name - explain how to use and reuse parameters
• Adding operations - introduce operations, show many there can be, what kind of, their purpose, pub/sub explained
• Securing operations - explain that server security applies to all the operations to all channel, but if you have different security per operation then you can use security prop on operation level
• Adding messages - add simple message as in previous examples, explain most important parts, explain there can be one or multiple (oneOf) under operation. Talk about contentType and add note about defaultSchema. Also show how to reuse from components
• Payload schema - more complex message example with payload added using JSON Schema and also Avro schema, and explanation how to specify them. And schema reuse from components
• AsyncAPI reusable parts - talk about $ref concept, introduce and explain that $ref can point to the same document, other document in local system, and also external urls. What about password to external url? Say that for local references people should use components
• Reuse with traits - explain trait concept and how it works
• Organizing document with tags - explain different tags info in different parts of AsyncAPI, their purpose (in docs rendering for example)
• Extending AsyncAPI specification - explain what to do when something you need is not yet supported by the specification, some field is missing or stuff like that. Explain that one way is to contribute (link) another to use -x <- and this is the core of this document, show extensions in action

Writing them is a huge learning experience 💪🏼 just 12 new docs 😄
I just put a really short description. I think that each needs separate issue, discussion about scope and then writing

[quetzalliwrites]

amazing work and writeup!!! thank you 🙏

[quetzalliwrites]

One quick reminder is that the Getting Started is a quickstart. It won't be a quickstart if we extended it with ALL OF THESE NEW TOPICS.

So let's add all these topics, but they're beyond the scope of our Quickstart.

[quetzalliwrites]

I have added this amazing info and proposal to my discussion of proposed 2023 Docs projects to take on; it's now ready for the community to vote on. 👍

[mtitinger]

Hello all,

IDK if this topic is considered closed, but here is some input.

I am considering using AsyncAPI as a formalism to do Model-based design. This idea is that adding properties to our device ecosystem is first done by describing the properties in the form of a schema.yaml, and ideally using generator for the different bindings (mqtt/c++) and documentation we need.

I have a prototype model repo, validated with AsyncStudio, and c++ generation produces code I can imagine to use in an embedded context, so far so good. One source of hesitation for me at this point is the complexity of aggregating several schema files. Ideally I do not wish to ask my contributors to add new channels, components, messages, traits etc... is the same file.

There are few example here and there on using refs, or python tooling to aggregate or split schema part, but it seems a bit fiddly to me at least, so I'm not sure this is the right way to go.

Some tutorial and example material for "distributed" model files would be great.

It seems quite natural to have for each functional blocs of technical domain in the system, a dedicated schema file, with channels, message, payload layouts, etc... that the framework is able to aggregate to one schema file that can be used for generation.

Thanks and regards,
Marc.

[derberg]

I feel like you should put this comment in https://github.com/orgs/asyncapi/discussions/814

[mtitinger]

Indeed, makes sense, thanks :)