Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: created a Glossary list #1784

Closed
Closed
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 105 additions & 0 deletions pages/docs/community/glossary.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
---
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Heyo, your directory structure is wrong because it's missing the Community content bucket folder. 😄 We are storing our Style Guide in the Community content bucket so your directory needs to be:
asyncapi.com/docs/community/style-guide/glossary.

Copy link
Member

@quetzalliwrites quetzalliwrites Jun 16, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P.S. I didn't mention this before because we JUST merged our new Community content bucket into the docs this week... but now that we have a LIVE Community content bucket in the docs, we actually should be authoring community docs directly in the /Community repo. (We actually have similar behavior/process in place for tools and specification docs too! Tools and specification docs are actually stored in their repoes and then copies to our website repo docs.)

I would work on your second draft and create a NEW PR in the community repo when you have it ready to review.

Please let me know if this doesn't make sense!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will need more explanation on this.
I currently have the following and the docs resides inside the 'Pages' folder as shown in the screenshots below.
image

second screenshot.
image

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, exactly! The sub-folder community inside the /docs directory is where the Style Guide will live.

That said, please note that your glossary document should be inside a NEW sub-folder of Style Guide. The URL for your document should be as follows: asyncapi.com/docs/community/style-guide/glossary.

Please let me know if this makes sense, we can always have another quick call too 💜

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

image

I noticed that, too and fixed it up. Thanks for calling that out.

Copy link
Member

@quetzalliwrites quetzalliwrites Jun 28, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SOOOO CLOSE, @CynthiaPeter. 😄✌🏽

1

Please note, however, that the sub-directory style-guide is missing a dash to separate the words.

As noted above, the URL for your document should be as follows: asyncapi.com/docs/community/style-guide/glossary.

2

Your new sub-directory style-guide is missing it's own section.md and index.md files. Sub-directories need those elements too. (please let me know if this doesn't make sense!)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you, @alequetzalli
I fixed these.

However, is there a guide on how we decide what goes into the _section.md and index.md page?

And if you have the time, I'd like to connect and have a call to talk about this and the onboarding guide. I have some drafts and ideas, but I am not exactly sure how to go about it.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, there is def best practices on what you need to place in both those files. Let's go over this again in a call 😄.

I see you sent me a DM to pick a day/time for that call, so I will follow up with you offline to help unblock you.

title: Glossary
weight: 10
---


This Glossary serves as a central location for terms that appears in the AsyncAPI documentation. If you find a term that you wish was defined here, please post an [issue requesting it](https://github.com/asyncapi/website/issues).


## API
The general definition of "Application Program Interface" can refer to different things for different people. However, in this case, APIs refer to different kinds of APIs, including HTTP-based, Async, and Event-driven Architecture.


## AsyncAPI
AsyncAPI is an open specification that allows you to describe and document asynchronous APIs (Application Programming Interfaces). It focuses on the communication patterns and message-driven architectures commonly found in event-driven systems, such as message queues, publish-subscribe systems, and streaming platforms.


## AsyncAPI document
An AsyncPI document is a file that defines and annotates the different components of a specific Event-Driven API.


## Bindings
A "binding" (or "protocol binding") is a mechanism to define protocol-specific information. Therefore, a protocol binding MUST define protocol-specific information only.


## Consumer
In an Event Driven Architecture (EDA), a consumer is an application that listens for a particular event from a broker and reacts to it.


## EDA
EDA stands for Event-Driven Architecture, an architectural pattern that structures software systems around event production, detection, and consumption. In an event-driven architecture, components or services communicate by producing and consuming events representing significant changes or occurrences in the system.


## Event
An event is a message that provides details of something that has already occurred.

An Event-Driven Architecture (EDA) uses events to trigger and communicate between services and is common in modern applications built with microservices.


## Identifier
This field represents a unique universal identifier of the application the AsyncAPI document defines. It must conform to the URI format, according to RFC3986.


## Message-driven APIs
Message-driven APIs, also known as Messaging APIs, facilitate communication between different components or services by exchanging messages. Instead of traditional request-response patterns in synchronous APIs, message-driven APIs rely on asynchronous messaging to enable decoupled and loosely coupled communication.


## Microservices
Microservices are a software architecture approach where applications are divided into small, independent services that communicate with each other through APIs. Each microservice focuses on a specific function, allowing scalability, agility, fault isolation, and technology flexibility.


## Modelina
Modelina is a library for generating data models based on inputs such as AsyncAPI, OpenAPI, or JSON Schema documents.


## Producer
A producer is an application that senses state changes (events) and publishes those events as messages. An event indicates a state change or update triggered by a user's/device's action.


## Protocol
A protocol is a set of rules that specifies how information is exchanged between applications and/or servers.


## ProtocolVersion
The version of the protocol used for the connection.


## Studio
Also known as the AsyncAPI studio is a tool that allows you to develop an AsyncAPI document, validate it, preview it, convert it to the latest version, and visualise event flows.




<!---
TODO: I need help deciding what these terms could be fit for and will appreciate any help or suggestions I can get.

AsyncAPI specification
AsyncAPI spec
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's stick to the full spelling of "AsyncAPI specification" and only list/define that term in this Glossary. Adding the abbreviation of "AsyncAPI spec" would be superfluous. 😄✌🏽

AsyncAPI file
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The history behind all these variations is that for a while, folks were saying BOTH AsyncAPI file and AsyncAPI document. Naturally, this raises confusion due to it's inconsistency.

Finally, sometime late last year the community decided to stick to one term: AsyncAPI document. So for this Glossary and all other docs, the only mentions should be for the AsyncAPI document.

AsyncAPI specification file
AsyncAPI instance
AsyncAPI definition
AsyncAPI contract

Secondly, in writing AsyncAPI, are there any variants? like these:

- asyncAPI
- Async API

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes! Many people write it INCORRECTLY. 😂

The only correct way to write our oss project name is AsyncAPI.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok. Done this.
We can highlight this information in an "important" callout.

image

Let me know if this is something we want to do or if there are other ways to make this obvious; that'll be great too. Also, I'll like to know what flavour of Markdown we use for writing docs. It's my first time using the "Remember" tag. I kept spelling it with low caps "r" and wondered what I did wrong.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure! A remember block could make great sense since this is a VERY common mistake :D

I noticed that in different cases, it is spelt differently. Do we want to specify anything?

Finally, I'll apprecite new words to be added. Thanks
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since AsyncAPI currently built 6 tools, as shown on our website, I would also include a definition for all 6 of those tools.

Screen Shot 2023-06-15 at 6 59 33 PM


-->