diff --git a/docs/onboarding-guide/_section.md b/docs/onboarding-guide/_section.md new file mode 100644 index 000000000..db05ea1fd --- /dev/null +++ b/docs/onboarding-guide/_section.md @@ -0,0 +1,4 @@ +--- +title : 'AsyncAPI docs onboarding Guide' +weight : 10 +--- \ No newline at end of file diff --git a/docs/onboarding-guide/docs-tools-and-processes.md b/docs/onboarding-guide/docs-tools-and-processes.md new file mode 100644 index 000000000..2ee9cb341 --- /dev/null +++ b/docs/onboarding-guide/docs-tools-and-processes.md @@ -0,0 +1,40 @@ +--- +title : 'Docs Tools and Processes' +weight : 10 +--- + +## Docs Tools and Processes +The following sections will guide you on what tools you will need and how to contribute to docs’ projects. Following tools and guidelines will help you with creating and maintaining docs processes. + +### Create new docs directories/folders +To create a new folder, take the following steps: +1. Indentify the content bucket your document shall fall under. +2. Open the project locally and navigate to the parent folder. +3. On the parent folder, right-click and click on 'new-folder'. +4. Give an appropriate name to the new-folder. +5. Add the following two files to the new-folder: + 1. `index.md` : This file is often used as the main content for a website's directory or specific webpage. It's called "index" because many web servers are configured to automatically look for an "index" file when accessing a directory. When you access a directory on a web server, if an "index.md" file is present, it will be displayed as the default page for that directory. + 2. `_section.md` : This file is used for reusable components or partial content within a website's structure. Use this file to define the page's ‘title’ and ‘weight’. Where title is used to define a ‘human-readable’ title, and weight is used to control the order or priority of how sections or components are displayed. +6. After successfully creating these pages, you can start editing the index page. + +```mermaid +flowchart LR + A[parent Folder] --> B[new Folder] + B[new Folder] --> C[index.md] + B[new Folder] --> D[_section.md] + B[new Folder] --> E[example-doc-1.md] + B[new Folder] --> F[example-doc-2.md] +``` + +## Create a docs Pull Request (PR) +Contributing to open source involves actively participating in a project by proposing changes such as code enhancements, test modifications, documentation updates, or addressing minor issues like typos and broken links. This section will guide you through creating and submitting a pull request. + +### Opening a Docs' PR +- A Docs’ PR should solve one documentation problem. +- Remember to first open a docs issue before creating a PR if there is no current issue for the docs task you want to accomplish. +- Use the [conventional commit style](https://github.com/asyncapi/.github/blob/master/CONTRIBUTING.md#conventional-commits) when creating PRs. Always create a docs issue or PR with the `docs:` prefix in the title. +- Check your contribution and ensure it follows the AsyncAPI style guide. +- Tag other technical writers to review the document. +- Tag an engineer or subject matter expert (SME) to review the technical details. +- After implementing all requested feedback, update your PR and wait for further feedback or a merge. + diff --git a/docs/onboarding-guide/index.md b/docs/onboarding-guide/index.md new file mode 100644 index 000000000..457e9fb54 --- /dev/null +++ b/docs/onboarding-guide/index.md @@ -0,0 +1,16 @@ +--- +title : 'AsyncAPI docs onboarding Guide' +weight : 10 +--- + +## AsyncAPI docs onboarding Guide +This section is a guide for new technical writers rather than a comprehensive reference manual detailing specific rules for contributing to AsyncAPI documentation. Please refer to the [contributing guidelines](https://github.com/asyncapi/community/blob/master/CONTRIBUTING.md) to learn more about how you can contribute. + +This section provides onboarding guides for new technical writers who join the AsyncAPI community. This onboarding guide aims to help technical writers: +- Understand tools, technologies, and processes in our docs. +- Understand consumers of the documentation. +- Identify teammates and SMEs (Subject matter experts). +- Make changes to the documentation. +- Receive feedback from the reviewer. +- Find bugs and create issues. +- Publish changes.