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..e0a8e9c70 --- /dev/null +++ b/docs/onboarding-guide/docs-onboarding-checklist.md @@ -0,0 +1,22 @@ +--- +title: 'Docs onboarding checklist' +weight: 30 +--- +## AsyncAPI docs onboarding checklist + +As an open-source initiative with a global community, technical writer contributors should learn about our governance documents, documentation processes, and communication channels. + +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 [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). +- [ ] 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. diff --git a/docs/onboarding-guide/index.md b/docs/onboarding-guide/index.md new file mode 100644 index 000000000..06860c37c --- /dev/null +++ b/docs/onboarding-guide/index.md @@ -0,0 +1,22 @@ +--- +title: 'Introduction' +weight: 10 +--- +## Technical writer onboarding guide + +The AsyncAPI technical writer onboarding guide teaches new community members how to contribute to our documentation effectively. + +> 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). + +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. + + + diff --git a/docs/onboarding-guide/prerequisite-knowledge.md b/docs/onboarding-guide/prerequisite-knowledge.md new file mode 100644 index 000000000..79ad5b454 --- /dev/null +++ b/docs/onboarding-guide/prerequisite-knowledge.md @@ -0,0 +1,36 @@ +--- +title: 'Prerequisite knowledge' +weight: 40 +--- + +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 +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. + +## 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 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, you must learn how to read, write, and validate these formats. + +## Understanding Event-Driven Architecture +[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, 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. 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..3f80f2bb8 --- /dev/null +++ b/docs/onboarding-guide/technical-writer-contributor-responsibilities.md @@ -0,0 +1,14 @@ +--- +title: 'Technical writer contributor responsibilities' +weight: 20 +--- + +In the AsyncAPI community, technical writers collaborate with other technical writers, Subject Matter Experts (SME), designers, engineers, and core maintainers. + +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. +* Join documentation community meetings/streams to connect with the community.