Skip to content

Commit

Permalink
docs: added docs for creating new docs directories and opening a docs…
Browse files Browse the repository at this point in the history
… PR under community content bucket
  • Loading branch information
MahendraDani committed Dec 5, 2023
1 parent 1547693 commit 2c332ca
Show file tree
Hide file tree
Showing 3 changed files with 60 additions and 0 deletions.
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 : 'AsyncAPI docs onboarding Guide'
weight : 10
---
40 changes: 40 additions & 0 deletions docs/onboarding-guide/docs-tools-and-processes.md
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.

16 changes: 16 additions & 0 deletions docs/onboarding-guide/index.md
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.

0 comments on commit 2c332ca

Please sign in to comment.