Add an AsyncAPI poster showing all features at a glance #425
Comments
|
I love this idea and I am excited to see what others think this poster should include. |
|
for me these are always like a good cheat sheet, so highlighting all features:
and also:
Anythink I'm missing? Might be we need 2 posters, one for AsyncAPI Specification, one for AsyncAPI tools, or event one more for AsyncAPI Initiative where we talk separately about the community 🤔 |
|
Yeah think the idea is great. Think we might also want to include the basics, or have two files maybe? Things I would like to see (if never seen AsyncAPI):
Maybe an intro into AsyncAPI cheatsheet too? |
|
This issue has been automatically marked as stale because it has not had recent activity 😴 It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation. There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model. Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here. Thank you for your patience ❤️ |
|
I think this is still relevant! I can't remove the |
|
This issue has been automatically marked as stale because it has not had recent activity 😴 It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation. There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model. Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here. Thank you for your patience ❤️ |
|
This didn't have enough traction. Not sure if its still relevant. |
|
This issue has been automatically marked as stale because it has not had recent activity 😴 It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation. There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model. Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here. Thank you for your patience ❤️ |
|
I still think this can be useful but to be honest, after a year, not sure if this is gonna happen. Do you still consider it something we wanna do? |
|
I also think it is useful, not only a poster, kind of infographic too. We just need someone talented who could design it. And all of us can help defining what content should go there |
|
I really like the idea and would have wanted to take it on, but I'm concentrating on a mentorship program this month, so I won't have time to work on it at the moment @smoya. If it's still open by next month, though, I'll fo for it 🥰🥰😌. |
|
This issue has been automatically marked as stale because it has not had recent activity 😴 It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation. There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model. Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here. Thank you for your patience ❤️ |
|
@Mayaleeeee first someone need to specify the content, and then the poster could be worked on. Maybe check in slack, in #specification channel, maybe someone would like to help, maybe in #docs ? |
|
Thanks @derberg |
|
Hi, I'd love to work on this project, I'm interested in this issue and would love to collaborate with anyone interested too |
|
@Miracle56u hey, thanks What brings you here? what skills you put on the table? design or? cause this task has 2 challenges: define content + define design |
|
@derberg we had a meeting two days ago and this project was discussed, and I developed interest for the project to bring my design skill to the table, even though I'll yet need further clarity and understanding of the project. |
|
awesome, here are some of the examples of such "posters" (more like a cheatsheets)
oh looks like there is a whole service about it https://cheatography.com/ anyway, we need content, and it is not easy to provide, my only idea is that we need to hope on a call, do brainstorming and come up with something. @smoya thoughts? |
Thanks, Miracle. |
|
Thanks Mayaleeeee! |
|
Okay @derberg |
|
Cheat Sheet Subjects:
So we think on online and printable version. We just need to remember that they are easy to edit, sources are in markdown or something similar. Cheat sheets could have a QR code that takes you to online version of the cheat sheet - cool for people that use printed version. |
|
ok then, lets do MVP with bounty support: scope:
out of scope: I know @Mayaleeeee is very much motivated to do it, including driving discussion - so let us use the opportunity that we have website maintainer wanting to do the job |
Bounty Issue's service commentText labels: @asyncapi/bounty_team |
Yes, I am. |
|
@Mayaleeeee you are now officially assigned for the work. Super excited about this bounty issue 🚀 |
Bounty Issue's Timeline
Please note that the dates given represent deadlines, not specific dates, so if the goal is reached sooner, it's better. |
|
Core
Features: Binding
channels:
userSignedUp:
description: This channel contains a message per each user who signs up in our application.
address: user_signedup
messages:
userSignedUp:
$ref: '#/components/messages/userSignedUp'
bindings:
kafka:
bindingVersion: '0.5.0'
partitions: 10
replicas: 2
topicConfiguration:
cleanup.policy: ["delete", "compact"]
retention.ms: 604800000
retention.bytes: 1000000000
delete.retention.ms: 86400000
max.message.bytes: 1048588Multi Format SchemaDefault is components:
schemas:
userSignedUp:
type: object
properties:
userId:
type: integer
description: This property describes the id of the user
userEmail:
type: string
description: This property describes the email of the userYou can use any other schema you want. Avro example components:
schemas:
userSignedUp:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
schema:
type: record
name: UserSignedUp
namespace: com.company
doc: User sign-up information
fields:
- name: userId
type: int
- name: userEmail
type: stringProtobuf example components:
schemas:
userSignedUp:
schemaFormat: 'application/vnd.google.protobuf;version=3'
schema: |
message UserSignedUp {
int32 user_id = 1;
string user_email = 2;
}and make it clear that there are also other schema formats, not just protobuf or avro, that can be used Extensionsway to extend standard AsyncAPI spec with additional fields asyncapi: 3.0.0
info:
title: Cool Example
version: 0.1.0
x-linkedin: '/company/asyncapi' ReusabilityReusability inside single AsyncAPI documentcomponents:
messages:
UserSignedUp:
payload:
$ref: '#/components/schemas/UserSignedUp'
schemas:
UserSignedUp:
type: object
properties:
displayName:
type: string
description: Name of the user
email:
type: string
format: email
description: Email of the userReusability outside document, pointing to a filecomponents:
messages:
UserSignedUp:
payload:
$ref: '#/components/schemas/UserSignedUp'
schemas:
UserSignedUp:
$ref: './userSchema.json'Reusability outside document, pointing to URLcomponents:
messages:
UserSignedUp:
payload:
$ref: '#/components/schemas/UserSignedUp'
schemas:
UserSignedUp:
$ref: http://localhost:8080/apis/registry/v2/groups/my-group/artifacts/UserSignedUpTraitstbc |
|
recording of meeting: https://www.youtube.com/watch?v=6lVMY_Fc0Vs |
Thanks a lot! @derberg Your explanation was great. |
Project Progress Overview: Weeks 1-2 UpdateHello everyone! During the first and second weeks, I focused on learning about cheat sheet design, including the best approaches for creating a user-friendly cheat sheet poster. In the first week, I had a livestream meeting with Lukasz where we discussed the cheat sheet and how to approach it. You can find the link to the meeting here. Here are some of the examples Lukasz mention and I have been exploring. https://media.cheatography.com/storage/thumb/hulj_nginx-config.750.jpg For next week: 15/04/2024 - 19/04/2024 I'd like to take the week off for my final exams and would return next week to start working on the design. cc @aeworxet Thank you, and have a great day! |
|
Upon request of the Bounty Program Participant (@Mayaleeeee), the Bounty Issue's Timeline is extended. Bounty Issue's Timeline Extended
Please note that the dates given represent deadlines, not specific dates, so if the goal is reached sooner, it's better.Keep in mind the responsibility for violations of the Timeline. |
Project Progress Overview: Week 4 UpdateAfter analyzing the discussion on the content for the AsyncAPI Cheat Sheet, I designed a layout that best captures all of our ideas and suggestions. You can easily access the design below 👇🏾 or via this Figma link. cc @derberg
|
|
Hey, nice first version! Could it be that binding examples are on one side and schemas on the other? and extensions and reusability in middle? as now it is a bit chaotic. there are some errors in yaml examples, but these are like "grammar" issues we can deal at the end. Take into account that we could print it as brochure, 2 sided, so bindings and multi schema examples, can be all on the other side, and on first side he can put basics |
Alright. I'll do that and come up with something. Thanks for the feedback. |
|
Hi @derberg these are the YAML snippets you requested. Protocol BindingsBinding - Channels Binding - Operations Binding - Message Binding - Server Multi Format SchemaDefault - AsyncAPI Schema Avro Example Protobuf ReusabilitySingle document URL To a file Extension |
|
Ok, so we should have a poster on two A4 pages, so we can print it on one card page 1 - should be basic explanation and core features so, Page 1 About AsyncAPIFixed content: Please try instead of one box with above text, have them all shared in a context of a picture:
FeaturesI think we can get rid of the box and provide texts in context, where example YAML samples are because of the amount of snippets for bindings + multiformat + reusability make sure they end up in Page 2 with above descriptions. in case of MultiFormat - the visual with JSON and AsyncAPI Schema is not helping much so we can remove it imho so on Page 1 I guess only extensions would stay 🤔 and if because of all above, we get a bit more space to occupy on Page 1, we could maybe place QR codes that would point to Studio and CLI to promote them as core tools to work with AsyncAPI? Fixed snippetsProtocol BindingsBinding - Channels Binding - Operations Binding - Message Binding - Server Multi Format SchemaDefault - AsyncAPI Schema Avro Example Protobuf ReusabilitySingle document URL To a file Extension |
Based on the explanation above, this is the design I was able to come up with. @derberg |
|
I marked with red parts that are missing indent, or indent is barely visible with bare eye also marked one place where wrong part is bold
|
|
can't wait to get it print out and share with people at APIDays Helsinki |
|
work completed also 200 copies for APIDays Helsinki printed.
some followup work will be done in #2982 and any improvements to current design, I'll create issues whenever there is some feedback from any event @smoya thanks for suggesting this topic @Mayaleeeee huge thanks for great execution |
Bounty Issue Completed 🎉@Mayaleeeee, please go to the AsyncAPI page on Open Collective and submit an invoice for |
Reason/Context
I noticed people from serverlessworkflow.io have a poster image where they show all their features at a glance.
It seems like a cheat sheet but it's more like a "here is all you can do". See https://serverlessworkflow.io/img/sw-poster.png.
I believe creating one for AsyncAPI will help potential users to quickly see and show all the things AsyncAPI can do for them, meaning adoption could be easier.
Of course it can also be used as a small reference guide (even though it is not a cheat-sheet) to refresh developers knowledge.
As a user, those are few examples of questions the poster might answer to me:
Description
The text was updated successfully, but these errors were encountered: