[📑 Docs]: create AsyncAPI Docs Style Guide

[quetzalliwrites]

What Dev Docs changes are you proposing?

Let's finally get around to creating, designing, and incorporating an AsyncAPI Style Guide!

Why the need?

In tech jobs, we often focus on our technology's technical aspects, such as functionality and performance. However, the documentation for our technology is equally important to the code itself. A style guide ensures consistency and clarity, establishes a consistent voice and tone in your documentation, makes it easier for multiple writers to work together on a single doc, and helps ensure documentation is accurate and up-to-date. When all of your technical writers follow the same guidelines, it's easier for readers to find the information they need and understand how to use your product or OSS technology.

Where should the AsyncAPI Style Guide live?

My vote 🗳 is to put in under our soon-to-be added NEW content bucket, Community. An AsyncAPI Style Guide is a Community resource, so it makes sense to be under the Community content bucket.

What should the AsyncAPI Style Guide include?

1. About this guide: welcome docs contributors, detail your needs, and mention goals for your documentation.
2. Accessibility: Teach accessibility best practices for adding images, diagrams, colors, patterns, alt-text, and writing for audiences of all levels (docs should make sense to anyone new to your technology).
3. Code examples: include comments explaining each line of code; determine colors and formatting applied to code blocks in your docs.
4. Content buckets explanation: Your content organization should be determined by how you structure documentation via designated content buckets (i.e., Diátaxis framework). Explain to your readers what each content bucket is for and the appropriate writing style for that area.
5. Docs Contribution Guidelines: Don’t leave technical writers clueless about contributing to your docs! They must understand content selection, prioritization, review processes, and releases.
6. Inclusive language: Inclusive language enables everyone in your organization to feel valued, respected, and able to contribute their talents. Some examples:

• main v.s. master
• allowlist/denylist v.s. whitelist/blacklist
• placeholder data v.s. dummy data
• gender-neutral (EX: they/them v.s. he/him)

7. Voice & Tone: Your brand may be informal or a little bit on the serious side. Do you want emoji use in your Docs? Don’t forget to include writing style tips for keeping Docs easy to read and understand.
8. Grammar: Define guidelines for abbreviations and acronyms, active voice, capitalization, spelling, verb tense, etc.
9. Numbers: Define guidelines for numbers and words, commas in numbers, number ranges, etc.
10. Punctuation: Define guidelines for the Oxford comma, semi-colons, colons, dashes, hyphens, etc.
11. Formatting: Define guidelines for formatting notes and warning blocks, code blocks, white space, etc.
12. Internalization (i18n) & Localization: Docs should meet the language and cultural needs of new regions and multiple locales. (future goal, for when AsyncAPI has incorporated i18n)
13. Links: Design link structure in text, assets, external links, etc.
14. SEO: Identify best SEO practices for headers, URL structure, alt-text, etc.
15. Styling: Design your styling requirements for CSS code, font size, markdown, lists, images, diagrams, tables, etc.
16. Version Control: Explain how version control is incorporated for AsyncAPI because docs will consistently undergo much revision and redrafting. Understanding version control in docs helps us to track changes and identify when key decisions were made along the way.
17. Glossary: A glossary can help to ensure consistency in the use of terminology throughout your documentation, which can improve clarity and comprehension for readers. The guidelines can include instructions on the types of terms to include, how to define and format them, and how to maintain and update the glossary over time. (Source: OpenAI's ChatGPT)

Extra Resources

• Write the Docs: Style Guides
• Gatsby Style Guide
• Gatsby Docs Structure & Documentation Types
• Mozilla Style Guide
• Google Style Guide
• Microsoft Style Guide

---

Tasks to be assigned:

• [x] #1243
• [x] #1244
• [ ] #1245
• [x] #1246
• [x] #1247
• [ ] #1248
• [ ] #1249
• [ ] #1250
• [x] #1251
• [x] #1252
• [x] #1253
• [x] #1254
• [x] #1255
• [x] #1256
• [x] #1257
• [x] #1258
• [x] #1294

Code of Conduct

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

cc for visibility on the Community content bucket topic @Maniktherana @magicmatatjahu @akshatnema @AceTheCreator @derberg

[quetzalliwrites]

@AceTheCreator, do you have any open PRs for adding the new Community content bucket? Want to make sure I'm not duplicating work or whatever 😄

[quetzalliwrites]

@magicmatatjahu, how about this SVG for the new Community content bucket?

<svg xmlns="http://www.w3.org/2000/svg" width="35" height="35" viewBox="0 0 24 24" fill="none" stroke="#000000" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M17 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2"></path><circle cx="9" cy="7" r="4"></circle><path d="M23 21v-2a4 4 0 0 0-3-3.87"></path><path d="M16 3.13a4 4 0 0 1 0 7.75"></path></svg>

source: https://iconsvg.xyz/

[Amishakumari544]

Looks good to me when we need to start working on this. @alequetzalli

[magicmatatjahu]

@alequetzalli Good for me :) Do you wanna that I should create new bucket in docs?

[AceTheCreator]

@AceTheCreator, do you have any open PRs for adding the new Community content bucket? Want to make sure I'm not duplicating work or whatever 😄

I don't have any yet.

[quetzalliwrites]

@alequetzalli Good for me :) Do you wanna that I should create new bucket in docs?

@magicmatatjahu yes, would you? 😄😍😍😍😍😍 thank you ✨✨ yay!!!!!!

[quetzalliwrites]

Looks good to me when we need to start working on this. @alequetzalli

@Amishakumari544 you must first follow up in Slack DMs (as discussed offline) because I will provide onboarding instructions in our DMs on an individual level before assigning tasks :smile:

[akshatnema]

@alequetzalli I have a query that are we going to include this in the upcoming GSOD program? Because the program has been announced and we have a good opportunity to again participate in this event and onboard new Docs contributors in our community.

[Maniktherana]

@alequetzalli I have a query that are we going to include this in the upcoming GSOD program?

If it is I'd be interested in being a gsod intern. I'm already in talks with @alequetzalli so I'll be contributing either way.

[magicmatatjahu]

PR https://github.com/asyncapi/website/pull/1261

@alequetzalli

[quetzalliwrites]

@alequetzalli I have a query that are we going to include this in the upcoming GSOD program? Because the program has been announced and we have a good opportunity to again participate in this event and onboard new Docs contributors in our community.

That's a great question, and I knew it was bound to come up 😄

So the only concern I have with this idea is that we already have 4 project ideas that the community is voting on to use for GSoD 2023: https://github.com/orgs/asyncapi/discussions/533. I can add the style guide as a 5th idea to vote on, but I am also not sure we want GSoD interns with no prior TW experience working something more complex such as a style guide.

Anywho, I guess we should add this idea for the community to vote on, since we shouldn't make unilateral decisions ✌🏽

@akshatnema

[quetzalliwrites]

@alequetzalli I have a query that are we going to include this in the upcoming GSOD program?

If it is I'd be interested in being a gsod intern. I'm already in talks with @alequetzalli so I'll be contributing either way.

@Maniktherana The community votes to decide the GSoD proposed projects to include in our upcoming application. (vote and stay tuned!)

As for having interest in being elected to be an AsyncAPI GSoD 2023 intern, you will need to apply and interview with everyone else. (Once/if google announces acceptance of AsyncAPI Docs for 2023 GSoD.) Stay tuned and if we're accepted, then you'll follow our instructions to apply and interview at that time. ✌🏽

[octonawish-akcodes]

I am interested in when are we going to work on this @alequetzalli

[thulieblack]

Hey Ale, can I get assigned some of the issues😁😁

[quetzalliwrites]

I am interested in when are we going to work on this @alequetzalli

@octonawish-akcodes Great, you need to complete your onboarding steps as we've been discussing in DM. Let's stick to DMs until you've completed onboarding steps and then I will give you a task. (we have 17 tasks here, which is a lot! no worries, enough for all)

[quetzalliwrites]

Hey Ale, can I get assigned some of the issues😁😁

@thulieblack, I am going to assign two tasks to you to start. I want you to start by owning the About this guide https://github.com/asyncapi/website/issues/1243 and Accessibility https://github.com/asyncapi/website/issues/1244 tasks. I entrust those to you because those both require much dedication and the right friendly tone. 😄

Sync with me via DM to get you started (if you need too) and we can talk more about these in our upcoming 1:1. ✨

[rowe-morehouse]

Hi @alequetzalli !! I am applying for the Google Season of Docs ... Is there anything I can help you with here on the Style Guide to get started working with AsyncAPI?

[quetzalliwrites]

Hi @alequetzalli !! I am applying for the Google Season of Docs ... Is there anything I can help you with here on the Style Guide to get started working with AsyncAPI?

Hello @rowe-morehouse! Contributing to the docs is separate from your GSoD application, but great to hear! To start as a docs contributor, send me a DM in slack so that I can send you the onboarding tasks for our new writers. When you have completed the onboarding tasks, I will assign you a first task. ✨

[CBID2]

Hi @alequetzalli. I got my seo guide PR finished. It's #1059