[📑 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:

• [📑 Docs]: New style guide - About this guide #1684
• [📑 Docs]: new style guide - Accessibility #1685
• [📑 Docs]: new style guide - Code examples #1686
• [📑 Docs]: new style guide - Content buckets #1687
• [📑 Docs]: new style guide - Docs Contributions #1688
• [📑 Docs]: new style guide - Inclusive language #1689
• [📑 Docs]: new style guide - Voice & Tone #1690
• [📑 Docs]: new style guide - Grammar #1691
• [📑 Docs]: new style guide - Numbers #1692
• [📑 Docs]: new style guide - Punctuation #1693
• [📑 Docs]: new style guide - Formatting #1694
• [📑 Docs]: new style guide - Internalization (i18n) and Localization #1695
• [📑 Docs]: new style guide - Links #1696
• [📑 Docs]: new style guide - SEO #1697
• [📑 Docs]: new style guide - Styling #1698
• [📑 Docs]: new style guide - Version Control #1699
• [📑 Docs]: new style guide - Glossary #1700

Code of Conduct

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

[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 😄

[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 asyncapi/website#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