From 0a72e7ce93f789a8c3e4d92c5631ea7abc127db4 Mon Sep 17 00:00:00 2001 From: Nathan Barbarick Date: Mon, 20 Nov 2023 19:18:13 -0800 Subject: [PATCH 1/8] Add first elements of the onboarding guide. --- docs/onboarding-guide/_section.md | 4 ++ .../docs-onboarding-checklist.md | 43 +++++++++++++++ docs/onboarding-guide/index.md | 20 +++++++ .../prerequisite-knowledge.md | 52 +++++++++++++++++++ ...cal-writer-contributor-responsibilities.md | 14 +++++ 5 files changed, 133 insertions(+) create mode 100644 docs/onboarding-guide/_section.md create mode 100644 docs/onboarding-guide/docs-onboarding-checklist.md create mode 100644 docs/onboarding-guide/index.md create mode 100644 docs/onboarding-guide/prerequisite-knowledge.md create mode 100644 docs/onboarding-guide/technical-writer-contributor-responsibilities.md diff --git a/docs/onboarding-guide/_section.md b/docs/onboarding-guide/_section.md new file mode 100644 index 000000000..def3abfee --- /dev/null +++ b/docs/onboarding-guide/_section.md @@ -0,0 +1,4 @@ +--- +title: Onboarding guide +weight: 10 +--- \ No newline at end of file diff --git a/docs/onboarding-guide/docs-onboarding-checklist.md b/docs/onboarding-guide/docs-onboarding-checklist.md new file mode 100644 index 000000000..b5b00a9ea --- /dev/null +++ b/docs/onboarding-guide/docs-onboarding-checklist.md @@ -0,0 +1,43 @@ +--- +title: Docs onboarding checklist +weight: 10 +--- +## AsyncAPI docs onboarding checklist + +As an open source initiative with a global community, we ask participants to become familiar with our governance documents, community guidelines, and communication channels. + +## Contributor standards at AsyncAPI + +Complete the following to get started as a contributor to the AsyncAPI project: + +- [ ] Read the [AsyncAPI Code of Conduct](https://github.com/asyncapi/community/blob/master/CODE_OF_CONDUCT.md). +- [ ] Read the [Slack etiquette](https://github.com/asyncapi/community/blob/master/slack-etiquette.md). +- [ ] Join [the AsyncAPI Slack](https://asyncapi.com/slack-invite). +- [ ] Introduce yourself in the #01_introductions channel and the #13_docs channel. Ask any docs-related questions in #13_docs. +- [ ] Join the #03_specification and #11_contributing channels. +- [ ] [Visit the events page](https://www.asyncapi.com/community/events) and then add the AsyncAPI calendar to stay updated with community events. +- [ ] Join a [Thursday docs meeting](https://www.asyncapi.com/community). This is a monthly or bi-weekly opportunity to chat with maintainers and other community members in order to understand goals, ask questions, and get help. + +## Technical writing standards at AsyncAPI + +Complete the following to become familiar with technical writing standards and expectations at AsyncAPI: + +- [ ] Read the list of [technical writer contributor responsibilities](/community/onboarding-guide/technical-writer-contributor-responsibilities.md). +- [ ] Become familiar with the [AsyncAPI git workflow](https://github.com/asyncapi/community/blob/master/git-workflow.md). +- [ ] Read through and be familiar with the topics in [prerequisite knowledge](/community/onboarding-guide/prerequisite-knowledge.md). +- [ ] Become familiar with the AsyncAPI Style Guide. + +## Making a contribution + +Now that you're up to speed, you're ready to get fully on board by making your first contribution. To start writing for AsyncAPI, complete the following: + +- [ ] [Reach out to Alejandra](https://asyncapi.slack.com/team/U02AKC14WAJ) or your onboarding buddy and ask for a good first issue to work on. +- [ ] Become familiar with the [AsyncAPI Docs Board](https://github.com/orgs/asyncapi/projects/12/views/1). +- [ ] Become familiar with docs tooling and processes. +- [ ] Set up your computer's development environment to view, edit, and publish AsyncAPI projects. +- [ ] Fork the appropriate repository and follow the git workflow. +- [ ] Start contributing to the documentation. + +As always, reach out to the AsyncAPI community on Slack or open an issue on GitHub with questions or concerns. We're here to help! + + diff --git a/docs/onboarding-guide/index.md b/docs/onboarding-guide/index.md new file mode 100644 index 000000000..628c6648a --- /dev/null +++ b/docs/onboarding-guide/index.md @@ -0,0 +1,20 @@ +--- +title: 'Introduction' +weight: 0 +--- +## AsyncAPI docs onboarding guide + +This onboarding guide is for technical writers who are new to the AsyncAPI community to learn how to contribute. For information about contributing to the AsyncAPI codebase, see the [contributing document](https://github.com/asyncapi/community/blob/master/CONTRIBUTING.md). Although intended for a developer audience, writers can find descriptions of general contribution principles and workflows for AsyncAPI projects. + +The goal of this onboarding guide is to help technical writers understand the tools, technologies, and processes in our documentation. More specifically, this section will help new writers to: + +* Understand consumers of the documentation. +* Identify teammates and subject matter experts (SMEs). +* Find bugs and create issues. +* Make changes to the documentation. +* Receive feedback from reviewers. +* Publish changes. + +We encourage you to reach out to the community whenever you have questions. For specifics on communication channels and to move forward with onboarding, start with the [onboarding checklist](/onboarding-guide/docs-onboarding-checklist.md). + + diff --git a/docs/onboarding-guide/prerequisite-knowledge.md b/docs/onboarding-guide/prerequisite-knowledge.md new file mode 100644 index 000000000..ae93933a5 --- /dev/null +++ b/docs/onboarding-guide/prerequisite-knowledge.md @@ -0,0 +1,52 @@ +--- +title: 'Prerequisite knowledge' +weight: 20 +--- + +This section highlights the key technologies, concepts, and skills that technical writers should know when working on AsyncAPI documentation. While you don't need to know everything to begin contributing, you should understand the main concepts behind the documentation methodology and tools, as well as the technologies surrounding the AsyncAPI specification. + +### Documentation concepts + +#### Understanding of diátaxis + +[Diátaxis](https://diataxis.fr/) is a methodology that AsyncAPI uses to organize its documentation website into several categories, based on what users need. For an overview of how AsyncAPI's documentation uses diátaxis, see [this post](https://www.asyncapi.com/blog/changes-coming-docs). + +#### Competency in Markdown + +Markdown is a markup language used to format text for the web. AsyncAPI's docs are written in Markdown, which is then processed into HTML by the back end of the website. For an overview of how to write in Markdown, see [this reference](https://www.markdownguide.org/basic-syntax/). + +#### Familiarity with the open source ecosystem + +Understanding the concepts of open source software will help you become a strong contributor to this project. For an overview of the AsyncAPI governance model, see [Finding a Good Open Governance Model for AsyncAPI](https://www.asyncapi.com/blog/governance-motivation). To read AsyncAPI's charter, which gives a high-level overview of the organization, see [here](https://github.com/asyncapi/community/blob/master/CHARTER.md). + +### AsyncAPI concepts + +#### Knowledge of AsyncAPI + +Before contributing to the documentation, you should know what AsyncAPI is, how it's structured, and what purpose it serves. See [here](https://www.asyncapi.com/docs/concepts) for an overview of the major AsyncAPI concepts. + +You should also have a basic understanding of [the AsyncAPI specification itself](https://www.asyncapi.com/docs/reference/specification/v2.6.0). + +#### Familiarity with JSON and YAML + +Because an AsyncAPI definition can be written in both JSON and YAML, understanding how to read, write, and validate these formats is beneficial. See [this post](https://www.asyncapi.com/blog/json-schema-beyond-validation) for an overview of the JSON schema used in AsyncAPI. + +#### Understanding event-driven architecture (EDA) + +Event-driven architecture is the style of software design at the core of how AsyncAPI works. Therefore, you should understand the basics of EDA, including its benefits, use cases, and how AsyncAPI conceptually fits into the EDA ecosystem. To get started with EDA, see [here](https://www.asyncapi.com/docs/tutorials/getting-started/event-driven-architectures/). + +Be sure to have an understanding of these EDA concepts: + +* Message brokers, aka servers +* Topics, aka channels +* Queues +* Subscriptions +* Publisher/Subscriber (Pub/Sub) pattern + +#### Understanding key protocols + +AsyncAPI supports several protocols, including Kafka, AMQP, and MQTT. You should have a [basic understanding of these protocols](https://www.asyncapi.com/docs/concepts/protocol#what-is-a-protocol), including their use cases and how they work. + +For further discussion of the protocols supported by AsyncAPI, see [here](https://www.asyncapi.com/blog/asyncapi-and-apicurio-for-asynchronous-apis#kafka-amqp-mqtt-or-http-protocol-specific-properties). + + diff --git a/docs/onboarding-guide/technical-writer-contributor-responsibilities.md b/docs/onboarding-guide/technical-writer-contributor-responsibilities.md new file mode 100644 index 000000000..8f2bb5214 --- /dev/null +++ b/docs/onboarding-guide/technical-writer-contributor-responsibilities.md @@ -0,0 +1,14 @@ +--- +title: 'Technical writer contributor responsibilities' +weight: 30 +--- + +Technical writers will collaborate with other writers, SMEs, designers, developers, and maintainers to create quality technical documentation. + +Some of your responsibilities include: + +* Creating quality, easy-to-use, clear, and accurate documentation for internal and external audiences. +* Collaborating with other teammates to plan, create, and maintain documentation. +* Assisting other technical writers and members of the community. +* Reviewing and improving documentation. +* Joining community calls and meetings to learn more and share ideas. From 12aa478d22a824f1b38dc22b7c514ed6f7944f9f Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Thu, 18 Jan 2024 15:37:47 -0800 Subject: [PATCH 2/8] tw editorial rewrite --- .../docs-onboarding-checklist.md | 2 +- docs/onboarding-guide/index.md | 24 ++++++++++--------- .../prerequisite-knowledge.md | 2 +- ...cal-writer-contributor-responsibilities.md | 2 +- 4 files changed, 16 insertions(+), 14 deletions(-) diff --git a/docs/onboarding-guide/docs-onboarding-checklist.md b/docs/onboarding-guide/docs-onboarding-checklist.md index b5b00a9ea..da6e71d1b 100644 --- a/docs/onboarding-guide/docs-onboarding-checklist.md +++ b/docs/onboarding-guide/docs-onboarding-checklist.md @@ -1,6 +1,6 @@ --- title: Docs onboarding checklist -weight: 10 +weight: 30 --- ## AsyncAPI docs onboarding checklist diff --git a/docs/onboarding-guide/index.md b/docs/onboarding-guide/index.md index 628c6648a..06860c37c 100644 --- a/docs/onboarding-guide/index.md +++ b/docs/onboarding-guide/index.md @@ -1,20 +1,22 @@ --- title: 'Introduction' -weight: 0 +weight: 10 --- -## AsyncAPI docs onboarding guide +## Technical writer onboarding guide -This onboarding guide is for technical writers who are new to the AsyncAPI community to learn how to contribute. For information about contributing to the AsyncAPI codebase, see the [contributing document](https://github.com/asyncapi/community/blob/master/CONTRIBUTING.md). Although intended for a developer audience, writers can find descriptions of general contribution principles and workflows for AsyncAPI projects. +The AsyncAPI technical writer onboarding guide teaches new community members how to contribute to our documentation effectively. -The goal of this onboarding guide is to help technical writers understand the tools, technologies, and processes in our documentation. More specifically, this section will help new writers to: +> For a comprehensive understanding of the various ways you can contribute to the AsyncAPI Initiative, please consult the [AsyncAPI contributing guidelines](https://github.com/asyncapi/community/blob/master/CONTRIBUTING.md). -* Understand consumers of the documentation. -* Identify teammates and subject matter experts (SMEs). -* Find bugs and create issues. -* Make changes to the documentation. -* Receive feedback from reviewers. -* Publish changes. +The goal is providing docs contributors with the necessary tools and knowledge to: + +* Understand our documentation tools, technologies, and processes. +* Comprehend our documentation target audiences. +* Connect with teammates and subject matter experts (SMEs). +* Report documentation bugs via issues. +* Implement and propose updates to our documentation. +* Obtain and incorporate reviewers' feedback. +* Publish changes successfully. -We encourage you to reach out to the community whenever you have questions. For specifics on communication channels and to move forward with onboarding, start with the [onboarding checklist](/onboarding-guide/docs-onboarding-checklist.md). diff --git a/docs/onboarding-guide/prerequisite-knowledge.md b/docs/onboarding-guide/prerequisite-knowledge.md index ae93933a5..cd6d86809 100644 --- a/docs/onboarding-guide/prerequisite-knowledge.md +++ b/docs/onboarding-guide/prerequisite-knowledge.md @@ -1,6 +1,6 @@ --- title: 'Prerequisite knowledge' -weight: 20 +weight: 40 --- This section highlights the key technologies, concepts, and skills that technical writers should know when working on AsyncAPI documentation. While you don't need to know everything to begin contributing, you should understand the main concepts behind the documentation methodology and tools, as well as the technologies surrounding the AsyncAPI specification. diff --git a/docs/onboarding-guide/technical-writer-contributor-responsibilities.md b/docs/onboarding-guide/technical-writer-contributor-responsibilities.md index 8f2bb5214..54f5b232a 100644 --- a/docs/onboarding-guide/technical-writer-contributor-responsibilities.md +++ b/docs/onboarding-guide/technical-writer-contributor-responsibilities.md @@ -1,6 +1,6 @@ --- title: 'Technical writer contributor responsibilities' -weight: 30 +weight: 20 --- Technical writers will collaborate with other writers, SMEs, designers, developers, and maintainers to create quality technical documentation. From 2da49d0a66917d4f41aa17b89fac4a6b1ee246f7 Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Thu, 18 Jan 2024 15:55:00 -0800 Subject: [PATCH 3/8] tw editorial rewrite --- docs/onboarding-guide/docs-onboarding-checklist.md | 2 +- ...echnical-writer-contributor-responsibilities.md | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/onboarding-guide/docs-onboarding-checklist.md b/docs/onboarding-guide/docs-onboarding-checklist.md index da6e71d1b..e5dcb3abe 100644 --- a/docs/onboarding-guide/docs-onboarding-checklist.md +++ b/docs/onboarding-guide/docs-onboarding-checklist.md @@ -1,5 +1,5 @@ --- -title: Docs onboarding checklist +title: 'Docs onboarding checklist' weight: 30 --- ## AsyncAPI docs onboarding checklist diff --git a/docs/onboarding-guide/technical-writer-contributor-responsibilities.md b/docs/onboarding-guide/technical-writer-contributor-responsibilities.md index 54f5b232a..348ae8406 100644 --- a/docs/onboarding-guide/technical-writer-contributor-responsibilities.md +++ b/docs/onboarding-guide/technical-writer-contributor-responsibilities.md @@ -3,12 +3,12 @@ title: 'Technical writer contributor responsibilities' weight: 20 --- -Technical writers will collaborate with other writers, SMEs, designers, developers, and maintainers to create quality technical documentation. +In the AsyncAPI community, technical writers collaborate with other technical writers, Subject Matter Experts (SME), designers, engineers, and core maintainers. -Some of your responsibilities include: +Technical writer contributor responsibilities include: -* Creating quality, easy-to-use, clear, and accurate documentation for internal and external audiences. -* Collaborating with other teammates to plan, create, and maintain documentation. -* Assisting other technical writers and members of the community. -* Reviewing and improving documentation. -* Joining community calls and meetings to learn more and share ideas. +* Create quality, easy-to-use, clear, and accurate documentation for all audience levels. +* Collaborate with other contributors to propose, create, and maintain documentation. +* Support fellow technical writers and community members. +* Engage in documentation review processes and incorporate feedback. +* Join documentation community meetings/streams to connect with the community. From 6c09190b192ff0f60febc3bd1b59ddcdbb6e49f2 Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Thu, 18 Jan 2024 15:55:38 -0800 Subject: [PATCH 4/8] spacing fix --- .../technical-writer-contributor-responsibilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/onboarding-guide/technical-writer-contributor-responsibilities.md b/docs/onboarding-guide/technical-writer-contributor-responsibilities.md index 348ae8406..3f80f2bb8 100644 --- a/docs/onboarding-guide/technical-writer-contributor-responsibilities.md +++ b/docs/onboarding-guide/technical-writer-contributor-responsibilities.md @@ -10,5 +10,5 @@ Technical writer contributor responsibilities include: * Create quality, easy-to-use, clear, and accurate documentation for all audience levels. * Collaborate with other contributors to propose, create, and maintain documentation. * Support fellow technical writers and community members. -* Engage in documentation review processes and incorporate feedback. +* Engage in documentation review processes and incorporate feedback. * Join documentation community meetings/streams to connect with the community. From 883524aebfddeaf6d77b1b3d2cdc4f9cd32e1852 Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Fri, 19 Jan 2024 10:39:35 -0800 Subject: [PATCH 5/8] tw editorial rewrite --- .../docs-onboarding-checklist.md | 45 +++++-------------- 1 file changed, 12 insertions(+), 33 deletions(-) diff --git a/docs/onboarding-guide/docs-onboarding-checklist.md b/docs/onboarding-guide/docs-onboarding-checklist.md index e5dcb3abe..e0a8e9c70 100644 --- a/docs/onboarding-guide/docs-onboarding-checklist.md +++ b/docs/onboarding-guide/docs-onboarding-checklist.md @@ -4,40 +4,19 @@ weight: 30 --- ## AsyncAPI docs onboarding checklist -As an open source initiative with a global community, we ask participants to become familiar with our governance documents, community guidelines, and communication channels. +As an open-source initiative with a global community, technical writer contributors should learn about our governance documents, documentation processes, and communication channels. -## Contributor standards at AsyncAPI - -Complete the following to get started as a contributor to the AsyncAPI project: +Complete in order the following onboarding tasks: - [ ] Read the [AsyncAPI Code of Conduct](https://github.com/asyncapi/community/blob/master/CODE_OF_CONDUCT.md). -- [ ] Read the [Slack etiquette](https://github.com/asyncapi/community/blob/master/slack-etiquette.md). -- [ ] Join [the AsyncAPI Slack](https://asyncapi.com/slack-invite). -- [ ] Introduce yourself in the #01_introductions channel and the #13_docs channel. Ask any docs-related questions in #13_docs. -- [ ] Join the #03_specification and #11_contributing channels. -- [ ] [Visit the events page](https://www.asyncapi.com/community/events) and then add the AsyncAPI calendar to stay updated with community events. -- [ ] Join a [Thursday docs meeting](https://www.asyncapi.com/community). This is a monthly or bi-weekly opportunity to chat with maintainers and other community members in order to understand goals, ask questions, and get help. - -## Technical writing standards at AsyncAPI - -Complete the following to become familiar with technical writing standards and expectations at AsyncAPI: - +- [ ] Read the [AsyncAPI Slack etiquette](https://github.com/asyncapi/community/blob/master/slack-etiquette.md). +- [ ] Join [the AsyncAPI Slack workspace](https://asyncapi.com/slack-invite). +- [ ] Add the AsyncAPI calendar found in [the AsyncAPI events page](https://www.asyncapi.com/community/events). - [ ] Read the list of [technical writer contributor responsibilities](/community/onboarding-guide/technical-writer-contributor-responsibilities.md). -- [ ] Become familiar with the [AsyncAPI git workflow](https://github.com/asyncapi/community/blob/master/git-workflow.md). -- [ ] Read through and be familiar with the topics in [prerequisite knowledge](/community/onboarding-guide/prerequisite-knowledge.md). -- [ ] Become familiar with the AsyncAPI Style Guide. - -## Making a contribution - -Now that you're up to speed, you're ready to get fully on board by making your first contribution. To start writing for AsyncAPI, complete the following: - -- [ ] [Reach out to Alejandra](https://asyncapi.slack.com/team/U02AKC14WAJ) or your onboarding buddy and ask for a good first issue to work on. -- [ ] Become familiar with the [AsyncAPI Docs Board](https://github.com/orgs/asyncapi/projects/12/views/1). -- [ ] Become familiar with docs tooling and processes. -- [ ] Set up your computer's development environment to view, edit, and publish AsyncAPI projects. -- [ ] Fork the appropriate repository and follow the git workflow. -- [ ] Start contributing to the documentation. - -As always, reach out to the AsyncAPI community on Slack or open an issue on GitHub with questions or concerns. We're here to help! - - +- [ ] Read and familiarize yourself with the [prerequisite knowledge topics](/community/onboarding-guide/prerequisite-knowledge.md). +- [ ] Familiarize yourself with the _work-in-progress_ [AsyncAPI Style Guide](https://github.com/asyncapi/community/pulls?q=is%3Apr+is%3Aopen+style+guide). +- [ ] Read all docs under the following content buckets: `Concepts`, `Tutorials`, `Reference`. (Take the time to go through each tutorial.) +- [ ] Set up your local environment following our instructions for the [AsyncAPI git workflow](https://github.com/asyncapi/community/blob/master/git-workflow.md). +- [ ] Introduce yourself in AsyncAPI Slack in the #01_introductions channel and the #13_docs channel. Ask docs-related questions in #13_docs. +- [ ] [Reach out to Quetzalli in Slack DM](https://asyncapi.slack.com/team/U02AKC14WAJ) to request a good first docs issue. +- [ ] Attend [OPEN docs meetings](https://www.asyncapi.com/community/events) to chat with other maintainers, ask docs questions, and request help on docs blockers. From 3788518ba3a858648bf57e9dc6db2f35ed12db57 Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Fri, 19 Jan 2024 10:51:54 -0800 Subject: [PATCH 6/8] tw editorial rewrite, draft 1 --- .../prerequisite-knowledge.md | 49 ++++++------------- 1 file changed, 16 insertions(+), 33 deletions(-) diff --git a/docs/onboarding-guide/prerequisite-knowledge.md b/docs/onboarding-guide/prerequisite-knowledge.md index cd6d86809..81bf5cc61 100644 --- a/docs/onboarding-guide/prerequisite-knowledge.md +++ b/docs/onboarding-guide/prerequisite-knowledge.md @@ -3,50 +3,33 @@ title: 'Prerequisite knowledge' weight: 40 --- -This section highlights the key technologies, concepts, and skills that technical writers should know when working on AsyncAPI documentation. While you don't need to know everything to begin contributing, you should understand the main concepts behind the documentation methodology and tools, as well as the technologies surrounding the AsyncAPI specification. +Our prerequisite knowledge section highlights the key technologies, concepts, and skills technical writers should know when working on AsyncAPI documentation. While you don't need to know everything to begin contributing, you should understand the main concepts behind the documentation methodology and tools and the technologies surrounding the AsyncAPI specification. -### Documentation concepts +## Diátaxis framework and content buckets +[Diátaxis](https://diataxis.fr/) is a framework that AsyncAPI uses to organize its documentation into content buckets (categories). For an overview of how AsyncAPI's documentation uses diátaxis, see [this post](https://www.asyncapi.com/blog/changes-coming-docs). -#### Understanding of diátaxis +## Markdown syntax and `mermaid.js` diagrams +AsyncAPI's docs are written in [Markdown syntax](https://www.markdownguide.org/basic-syntax/). -[Diátaxis](https://diataxis.fr/) is a methodology that AsyncAPI uses to organize its documentation website into several categories, based on what users need. For an overview of how AsyncAPI's documentation uses diátaxis, see [this post](https://www.asyncapi.com/blog/changes-coming-docs). +Our diagrams are also written with [markdown syntax](https://mermaid.live/) thanks to the [mermaid.js](https://mermaid.js.org/) dependency. + +## Familiarity with the open-source ecosystem -#### Competency in Markdown +Understanding the concepts of open-source software will help you become a strong contributor to this project. For an overview of the AsyncAPI governance model, see [Finding a Good Open Governance Model for AsyncAPI](https://www.asyncapi.com/blog/governance-motivation). To read AsyncAPI's charter, which gives a high-level organization overview, see [here](https://github.com/asyncapi/community/blob/master/CHARTER.md). -Markdown is a markup language used to format text for the web. AsyncAPI's docs are written in Markdown, which is then processed into HTML by the back end of the website. For an overview of how to write in Markdown, see [this reference](https://www.markdownguide.org/basic-syntax/). - -#### Familiarity with the open source ecosystem - -Understanding the concepts of open source software will help you become a strong contributor to this project. For an overview of the AsyncAPI governance model, see [Finding a Good Open Governance Model for AsyncAPI](https://www.asyncapi.com/blog/governance-motivation). To read AsyncAPI's charter, which gives a high-level overview of the organization, see [here](https://github.com/asyncapi/community/blob/master/CHARTER.md). - -### AsyncAPI concepts - -#### Knowledge of AsyncAPI - -Before contributing to the documentation, you should know what AsyncAPI is, how it's structured, and what purpose it serves. See [here](https://www.asyncapi.com/docs/concepts) for an overview of the major AsyncAPI concepts. +## AsyncAPI knowledge +Before contributing to the documentation, you should know what AsyncAPI is, its structure, and its purpose. See [here](https://www.asyncapi.com/docs/concepts) for an overview of the major AsyncAPI concepts. You should also have a basic understanding of [the AsyncAPI specification itself](https://www.asyncapi.com/docs/reference/specification/v2.6.0). -#### Familiarity with JSON and YAML - -Because an AsyncAPI definition can be written in both JSON and YAML, understanding how to read, write, and validate these formats is beneficial. See [this post](https://www.asyncapi.com/blog/json-schema-beyond-validation) for an overview of the JSON schema used in AsyncAPI. - -#### Understanding event-driven architecture (EDA) - -Event-driven architecture is the style of software design at the core of how AsyncAPI works. Therefore, you should understand the basics of EDA, including its benefits, use cases, and how AsyncAPI conceptually fits into the EDA ecosystem. To get started with EDA, see [here](https://www.asyncapi.com/docs/tutorials/getting-started/event-driven-architectures/). - -Be sure to have an understanding of these EDA concepts: - -* Message brokers, aka servers -* Topics, aka channels -* Queues -* Subscriptions -* Publisher/Subscriber (Pub/Sub) pattern +## JSON and YAML +Because an AsyncAPI definition can be written in JSON and YAML, understanding how to read, write, and validate these formats is beneficial. See [this post](https://www.asyncapi.com/blog/json-schema-beyond-validation) for an overview of the JSON schema used in AsyncAPI. -#### Understanding key protocols +## Understanding Event-Driven Architecture +Event-Driven Architecture (EDA) is the style of software design at the core of AsyncAPI's work. Therefore, you should understand the basics of EDA, including its benefits, use cases, and how AsyncAPI conceptually fits into the EDA ecosystem. To get started with EDA, see [here](https://www.asyncapi.com/docs/tutorials/getting-started/event-driven-architectures/). +## Protocols used with AsyncAPI AsyncAPI supports several protocols, including Kafka, AMQP, and MQTT. You should have a [basic understanding of these protocols](https://www.asyncapi.com/docs/concepts/protocol#what-is-a-protocol), including their use cases and how they work. -For further discussion of the protocols supported by AsyncAPI, see [here](https://www.asyncapi.com/blog/asyncapi-and-apicurio-for-asynchronous-apis#kafka-amqp-mqtt-or-http-protocol-specific-properties). From 41075c1c5302bb731364f4881609646e43392512 Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Fri, 19 Jan 2024 10:55:45 -0800 Subject: [PATCH 7/8] fix mermaid.js mention --- docs/onboarding-guide/prerequisite-knowledge.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/onboarding-guide/prerequisite-knowledge.md b/docs/onboarding-guide/prerequisite-knowledge.md index 81bf5cc61..0fa84f8e0 100644 --- a/docs/onboarding-guide/prerequisite-knowledge.md +++ b/docs/onboarding-guide/prerequisite-knowledge.md @@ -11,7 +11,7 @@ Our prerequisite knowledge section highlights the key technologies, concepts, an ## Markdown syntax and `mermaid.js` diagrams AsyncAPI's docs are written in [Markdown syntax](https://www.markdownguide.org/basic-syntax/). -Our diagrams are also written with [markdown syntax](https://mermaid.live/) thanks to the [mermaid.js](https://mermaid.js.org/) dependency. +Our diagrams are created with [Mermaid markdown syntax](https://mermaid.live/) thanks to the [mermaid.js](https://mermaid.js.org/) dependency. ## Familiarity with the open-source ecosystem From 19b1e2a5721bec720e00c0bc6380df53fe8a4291 Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Fri, 19 Jan 2024 15:28:05 -0800 Subject: [PATCH 8/8] tw editorial rewrite: Draft 2 --- .../prerequisite-knowledge.md | 31 ++++++++++--------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/docs/onboarding-guide/prerequisite-knowledge.md b/docs/onboarding-guide/prerequisite-knowledge.md index 0fa84f8e0..79ad5b454 100644 --- a/docs/onboarding-guide/prerequisite-knowledge.md +++ b/docs/onboarding-guide/prerequisite-knowledge.md @@ -3,33 +3,34 @@ title: 'Prerequisite knowledge' weight: 40 --- -Our prerequisite knowledge section highlights the key technologies, concepts, and skills technical writers should know when working on AsyncAPI documentation. While you don't need to know everything to begin contributing, you should understand the main concepts behind the documentation methodology and tools and the technologies surrounding the AsyncAPI specification. +The prerequisite knowledge section highlights the key technologies, concepts, and skills our technical writers need for working with AsyncAPI documentation. You must understand the main concepts behind our documentation processes, content classification, and the AsyncAPI specification. ## Diátaxis framework and content buckets -[Diátaxis](https://diataxis.fr/) is a framework that AsyncAPI uses to organize its documentation into content buckets (categories). For an overview of how AsyncAPI's documentation uses diátaxis, see [this post](https://www.asyncapi.com/blog/changes-coming-docs). +AsyncAPI adopted the [Diátaxis](https://diataxis.fr/) framework to meet our specific needs, classifying our documentation into content buckets (categories). + +- `Concepts` define the concepts of AsyncAPI features. +- `Tutorials` teach beginner processes with AsyncAPI by doing, taking you step-by-step from Point A to Point B. +- `Tools` documents the AsyncAPI tools ecosystem. +- `Guide` teaches troubleshooting and understanding AsyncAPI's capabilities at a high level. +- `Reference` documents the AsyncAPI specification. +- `Migration` guides how to upgrade to a newer AsyncAPI version. +- `Community` explains our documentation processes, guidelines, and resources to community members. ## Markdown syntax and `mermaid.js` diagrams AsyncAPI's docs are written in [Markdown syntax](https://www.markdownguide.org/basic-syntax/). Our diagrams are created with [Mermaid markdown syntax](https://mermaid.live/) thanks to the [mermaid.js](https://mermaid.js.org/) dependency. - -## Familiarity with the open-source ecosystem - -Understanding the concepts of open-source software will help you become a strong contributor to this project. For an overview of the AsyncAPI governance model, see [Finding a Good Open Governance Model for AsyncAPI](https://www.asyncapi.com/blog/governance-motivation). To read AsyncAPI's charter, which gives a high-level organization overview, see [here](https://github.com/asyncapi/community/blob/master/CHARTER.md). -## AsyncAPI knowledge -Before contributing to the documentation, you should know what AsyncAPI is, its structure, and its purpose. See [here](https://www.asyncapi.com/docs/concepts) for an overview of the major AsyncAPI concepts. +## AsyncAPI concepts +Before contributing to the documentation, you should understand [the purpose of AsyncAPI](https://www.asyncapi.com/docs/tutorials/getting-started) and essential [AsyncAPI concepts](https://www.asyncapi.com/docs/concepts) _(i.e., servers, producers, consumers, channels, messages, etc.)_. -You should also have a basic understanding of [the AsyncAPI specification itself](https://www.asyncapi.com/docs/reference/specification/v2.6.0). +You should also fundamentally understand [the AsyncAPI specification](https://www.asyncapi.com/docs/reference/specification/latest). ## JSON and YAML -Because an AsyncAPI definition can be written in JSON and YAML, understanding how to read, write, and validate these formats is beneficial. See [this post](https://www.asyncapi.com/blog/json-schema-beyond-validation) for an overview of the JSON schema used in AsyncAPI. +Because an AsyncAPI definition can be written in JSON and YAML, you must learn how to read, write, and validate these formats. ## Understanding Event-Driven Architecture -Event-Driven Architecture (EDA) is the style of software design at the core of AsyncAPI's work. Therefore, you should understand the basics of EDA, including its benefits, use cases, and how AsyncAPI conceptually fits into the EDA ecosystem. To get started with EDA, see [here](https://www.asyncapi.com/docs/tutorials/getting-started/event-driven-architectures/). +[Event-Driven Architecture (EDA)](https://www.asyncapi.com/docs/tutorials/getting-started/event-driven-architectures/) uses events to trigger and communicate between services. (AsyncAPI is an open-source initiative that seeks to improve the current state of EDAs.) ## Protocols used with AsyncAPI -AsyncAPI supports several protocols, including Kafka, AMQP, and MQTT. You should have a [basic understanding of these protocols](https://www.asyncapi.com/docs/concepts/protocol#what-is-a-protocol), including their use cases and how they work. - - - +AsyncAPI supports several protocols, such as Kafka, AMQP, MQTT, and more. You will benefit from acquiring a [basic understanding of protocols most used with AsyncAPI](https://www.asyncapi.com/docs/concepts/protocol), including their use cases and how they work with AsyncAPI.