[📑 Docs]: add new tutorial Hello World for producer application

[asos-andrewpotts]

What Dev Docs changes are you proposing?

Regarding the Hello World example:

The description around this example confused me a little bit.
Why is this example written in the eyes of the subscriber? It starts with "Let's define an application that's capable of receiving".

Then the Async API document uses the word "publish:".

Normally I'd write a specification around the publisher and the messages it emits. I don't normally define the message that the subscriber expects to receive.

Wouldn't it be better describing it as "Let's define an application that's capable of publishing a message"......?

Code of Conduct

• I agree to follow this project's Code of Conduct

[github-actions]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup 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.

[asos-andrewpotts]

On reading the document again, I suppose I'm coming from a pub/sub perspective where the publisher documents the events that it publishes on topics and then one or more subscribers subscribe to them. In the pub/sub scenario subscribers don't specify the events they expect to receive as they have no choice over the matter; they are subscribing to another system's events.

The Hello World example is more akin to a application is defining the commands that it expects to be sent on a queue.
In these scenarios the receiver would document specifications of the commands it would receive. In a command model where there is one logical recipient, but one or more senders, then yes, the recipient would document it's message specification.

Message Type	Terminology	Topology	Who owns the specification?
Event	Publisher, Subscriber	One Publisher, Many Subscribers	Publisher
Command	Sender, Receiver	One Receiver, Many Senders	Receiver

I think I got confused because reading the documents in sequence, the previous sections talked about event-driven architectures but the very first example was not really publishing or subscribing to an event, it was written from a receiver application being sent a command.

Should we convert the example into an application publishing an event?

[derberg]

On reading the document again, I suppose I'm coming from a pub/sub perspective where the publisher documents the events that it publishes on topics and then one or more subscribers subscribe to them. In the pub/sub scenario subscribers don't specify the events they expect to receive as they have no choice over the matter; they are subscribing to another system's events.

it all depends on what is your use case for AsyncAPI. Is it only docs from consumer's point of view. Or maybe you are interested in code generation. Or maybe you have a WebSocket API where you send and receive messages. There is also a request/reply pattern in pub/sub, where you want to know what message you can sent to a services, and where you should specify where the reply should be sent. So yeah, it really depends on where you are coming from and what is your goal.

Should we convert the example into an application publishing an event?

what about we just provide another tutorial for publishing. So we keep the current one, Hello World, as Hello World for consumer application and add new Hello World for producer application?

@alequetzalli thoughts?

[github-actions]

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 ❤️

[nickshoe]

I mean... publish operation should refer to the act of publishing a message in a channel.

I'm confused too.

[derberg]

@alequetzalli can you have a look?

[sambhavgupta0705]

@alequetzalli ping pong

[quetzalliwrites]

Hey @derberg and @asos-andrewpotts, not sure how I missed this one!

First, thank you for sharing your thoughts with such detail, @asos-andrewpotts. I had to consider and process them.

Second, I must admit I align with Lukasz' recommendation. Let's keep the current one, Hello World, as Hello World for consumer application and add a new Hello World for producer application.

[derberg]

so yeah, this issue was created before v3 release

now, hello world document shows how to describe in AsyncAPI that app is receiving a message

would be still nice to have an example where app is sending a message

so Hello world - receiving a message and Hello world - sending a message and in the new document we could extent an example, that Hello world application drops a message to a broker every time the welcoming takes place

[quetzalliwrites]

Got it, thanks for the reply @derberg !

[quetzalliwrites]

@derberg, I have started the work here: #2981.

Do let me know what you think. 😸 💭

[github-actions]

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 ❤️