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: add first elements of the onboarding guide. #960

Merged
merged 11 commits into from
Jan 19, 2024
4 changes: 4 additions & 0 deletions docs/onboarding-guide/_section.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
title: Onboarding guide
weight: 10
---
22 changes: 22 additions & 0 deletions docs/onboarding-guide/docs-onboarding-checklist.md
Original file line number Diff line number Diff line change
@@ -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.
22 changes: 22 additions & 0 deletions docs/onboarding-guide/index.md
Original file line number Diff line number Diff line change
@@ -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.



36 changes: 36 additions & 0 deletions docs/onboarding-guide/prerequisite-knowledge.md
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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.
Loading