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]: consistent formatting and writing style throughout the documentation #3375

Open
1 task done
bandantonio opened this issue Nov 7, 2024 · 1 comment
Open
1 task done

Comments

@bandantonio
Copy link
Contributor

bandantonio commented Nov 7, 2024

What Dev Docs changes are you proposing?

Motivation

Many documentation pages use different formatting for the same content elements or don't use it at all. For example:

  • The first occurrence of a specific AsyncAPI-related term can either be italicized or not.
  • Abbreviations can be used with their full forms (in different variants) within a single page.
  • Bold formatting is used chaotically to grab attention and highlight ui elements the user should click on.
  • No consistent wording within a single page. For example:
    • The above diagram describes
    • The diagram above shows
    • The above diagram depicts

So, the idea is to make AsyncAPI docs more consistent by leveraging common formatting to the content and using the same word forms and constructions throughout the docs. Even though, the style guide for AsyncAPI docs is still under development (or not 😁) (see #1240 ) with no specific TTM, certain formatting is consistent regardless of the style guide used. It can be applied anyway, for example, for the points mentioned above.

Tasks

(the list will be expanded gradually as soon as new sections fall within the scope)

Code of Conduct

  • I agree to follow this project's Code of Conduct
@bandantonio
Copy link
Contributor Author

@quetzalliwrites or someone else, please assign me to this issue

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant