docs: created a Glossary list #1784
Conversation
✅ Deploy Preview for asyncapi-website ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify site settings. |
CynthiaPeter
changed the title
quetzalliwrites
added
📑 docs
area/docs
pages/docs/community/glossary.md
Outdated
| Secondly, in writing AsyncAPI, are there any variants? like these: | ||
|
|
||
| - asyncAPI | ||
| - Async API | ||
|
|
There was a problem hiding this comment.
Yes! Many people write it INCORRECTLY. 😂
The only correct way to write our oss project name is AsyncAPI.
There was a problem hiding this comment.
Ok. Done this.
We can highlight this information in an "important" callout.
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.
There was a problem hiding this comment.
Sure! A remember block could make great sense since this is a VERY common mistake :D
pages/docs/community/glossary.md
Outdated
|
|
||
| AsyncAPI specification | ||
| AsyncAPI spec | ||
| AsyncAPI file |
There was a problem hiding this comment.
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.
pages/docs/community/glossary.md
Outdated
| AsyncAPI specification | ||
| AsyncAPI spec |
There was a problem hiding this comment.
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. 😄✌🏽
pages/docs/community/glossary.md
Outdated
|
|
||
| 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 |
There was a problem hiding this comment.
Since AsyncAPI currently built 6 tools, as shown on our website, I would also include a definition for all 6 of those tools.
pages/docs/community/glossary.md
Outdated
| @@ -0,0 +1,105 @@ | |||
| --- | |||
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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!
There was a problem hiding this comment.
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.
second screenshot.
There was a problem hiding this comment.
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 💜
There was a problem hiding this comment.
I noticed that, too and fixed it up. Thanks for calling that out.
There was a problem hiding this comment.
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!)
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
|
Hello @alequetzalli Can you point me to the specific community repo where I must create the PR? I assume it is this one, but I'll like to be sure. Thank you. |
|
Yes, that is exactly right! That is the only community repo we have, so that is the correct place to put your work ✨ |
|
This pull request 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 pull request, add a comment with detailed explanation. There can be many reasons why some specific pull request 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 pull request forward. Connect with us through one of many communication channels we established here. Thank you for your patience ❤️ |
|
Don't you think we should close this PR as the related work is already been shifted by @CynthiaPeter to the community repo PR suggested by @alequetzalli ? |
|
Correct, closing cause this is going to be taken care of via asyncapi/community#769. |
Description
Related issue(s)
Reference to #1294
Notes: