-
-
Notifications
You must be signed in to change notification settings - Fork 113
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: added docs for creating new docs directories and opening a docs…
… PR under community content bucket
- Loading branch information
1 parent
1547693
commit 2c332ca
Showing
3 changed files
with
60 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
--- | ||
title : 'AsyncAPI docs onboarding Guide' | ||
weight : 10 | ||
--- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |