Rewrite Contributing and readme

CONTRIBUTING.md

@@ -1,60 +1,123 @@
 # Contributing Guidelines
 
-Thank you for your interest in improving the OpenSource documentation! We value and appreciate all feedback and contributions from our community, including requests for additional documentation, corrections to existing content, and to report technical issues with the documentation site. 
+Thank you for your interest in improving the OpenSource documentation! We value and appreciate all feedback and contributions from our community, including requests for additional documentation, corrections to existing content, and reports of technical issues with the documentation site. 
 
-The OpenSearch documentation team is dedicated to providing complete and best-in-class documentation. Thank you for your patience as we build our documentation team and content library. We appreciate your support and patience.
+## Finding contributions to work on
 
-## How to request changes
+If you’d like to contribute but don't know where to start, try browsing existing issues. Our projects use custom GitHub issue labels for status, version, type of request, and so on, but we recommend looking at any issues labeled `good first issue` first. 
 
-Before entering a change request, please read this document carefully. We want to make sure we have all the information necessary to effectively respond to your contribution. 
+## Contributing to the documentation site
 
-There are two ways to contribute: 1) create an issue where you describe the change and 2) create a pull request that contains the content to directly insert into the documentation.
+There are two ways to contribute: 
+1. [Create an issue](#create-an-issue) asking us to change the documentation.
+2. [Contribute documentation content](#contribute-content) yourself.
 
-**Create an Issue**
+## Create an issue
 
-Use the Github issue tracker to describe the change you'd like to make. 
+Use the GitHub issue tracker to describe the change you'd like to make: 
 
 1. Go to https://github.com/opensearch-project/documentation-website/issues and select *New issue*.
-2. Enter the requested information and include as much detail as possible, especially which version or versions the request affects.
+2. Enter the requested information, including as much detail as possible, especially which version or versions the request affects.
 3. Select *Submit new issue*. 
 
+The `untriaged` label is assigned automatically. During the triage process, the documentation team will add the appropriate labels, assign the issue to a technical writer, and prioritize the request. We may follow up with you for additional information. 
 
-The ‘untriaged’ label is assigned automatically. During the triage process, the documentation team will add the appropriate labels, assign the issue to a technical writer, and prioritize the request. We may follow up with you for additional information. 
+## Contribute content
 
+There are two ways to contribute content:
 
-**Create a pull request**
+- [Editing files directly in GitHub](#editing-files-in-github): Best for small changes like fixing a typo or adding a parameter. This approach does not require cloning the repository and does not let you test the documentation.
+- [Making changes locally and pushing to GitHub](#making-changes-locally): Best for changes you want to test locally first, like adding a table or section, or reorganizing pages. This approach requires setting up a local version of the repository and lets you test documentation.
 
-If you’d like to make a change directly to the content, create a pull request. If it’s a quick fix, we should be able to release the update quickly. Bigger requests might take a bit of time for us to review. 
+The workflow for contributing documentation is no different than the one for contributing code:
 
-Note that a pull request requires DCO sign off before we can merge it. You can use the -s command line option to append this automatically to your commit message, for example $ git commit -s -m 'This is my commit message'. For more information, see https://github.com/apps/dco.
+- Make your changes
+- Build locally to check your work (only possible if you are making changes locally)
+- Submit a [pull request](https://github.com/opensearch-project/documentation-website/pulls) (PR)
+- Maintainers review and merge your PR
 
-Before submitting, make sure to:
+If the change requires significant work, open an issue where we can first discuss your request.
 
-* Work against the latest source on the main branch.
-* Check existing open and recently merged pull requests to ensure that someone else hasn't addressed the problem already.
-* If the change requires significant work, open an issue where we can first discuss your request.
+### Before you start
 
-To create a pull request:
+Before contributing content, make sure to read the following resources:
+- [README](README)
+- [OpenSearch Project Style Guidelines](STYLE_GUIDE)
+- [API Style Guide](API_STYLE_GUIDE)
+- [Formatting Guide](FORMATTING_GUIDE) 
 
-1. Fork the repository.
-2. Modify the source. Make sure to focus on the specific change you are contributing. For example, if you also reformat the code, it will be hard for us to focus on your change.
-3. Test the code. Make sure that any local tests pass.
-4. Commit to your fork using clear commit messages.
-5. Create the [pull request](https://github.com/opensearch-project/documentation-website/pulls) and save it, making sure to answer the default questions in the pull request template.
+### Editing files in GitHub
 
-If you need additional support, GitHub provides documentation on [forking a repository](https://help.github.com/articles/fork-a-repo/) and [creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
+If you want to add a few paragraphs to a file, try this approach:
 
+1. [Fork this repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo).
 
-## Finding contributions to work on
+1. In your fork on GitHub, navigate to the file that you want to change.
+
+1. In the upper-right corner, select the dropdown with the pencil icon and select **Edit in place**. Edit the file.
+
+1. In the upper-right corner, select **Commit changes...***. Enter the commit message and optional description and select **Create a new branch for this commit and start a pull request**.
+
+
+### Making changes locally
+
+If you're making major changes to the documentation and need to see the rendered HTML before submitting a pull request, here's how to make the changes and view them locally:
+
+1. [Fork this repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo) and clone your fork.
+
+1. Navigate to the repository root.
+
+1. Install [Ruby](https://www.ruby-lang.org/en/) if you don't already have it. We recommend [RVM](https://rvm.io/), but use whatever method you prefer:
+
+   ```
+   curl -sSL https://get.rvm.io | bash -s stable
+   rvm install 2.6
+   ruby -v
+   ```
+
+1. Install [Jekyll](https://jekyllrb.com/) if you don't already have it:
+
+   ```
+   gem install bundler jekyll
+   ```
+
+1. Install dependencies:
+
+   ```
+   bundle install
+   ```
+
+1. Build:
+
+   ```
+   sh build.sh    
+   ```
+
+1. If the build script doesn't automatically open your web browser (it should), open [http://localhost:4000/docs/](http://localhost:4000/docs/).
+
+1. Create a new branch against the latest source on the main branch. 
+
+1. Edit the Markdown files that you want to change.
+
+1. When you save a file, marvel as Jekyll automatically rebuilds the site and refreshes your web browser. This process can take anywhere from 10 to 30 seconds.
+
+1. When you're happy with how everything looks, commit, [sign off](https://github.com/src-d/guide/blob/9171d013c648236c39faabcad8598be3c0cf8f56/developer-community/fix-DCO.md#how-to-prevent-missing-sign-offs-in-the-future), push your changes to your fork, and submit a pull request.
+
+    Note that a pull request requires DCO sign off before we can merge it. You can use the -s command line option to append this automatically to your commit message, for example $ git commit -s -m 'This is my commit message'. For more information, see https://github.com/apps/dco.
+
+
+### Review process
+
+We greatly appreciate everyone who takes the time to make a contribution. We will review all contributions as quickly as possible. If it’s a quick fix, we should be able to release the update quickly. Bigger requests might take a bit of time for us to review. 
 
-If you’d like to contribute but don't know where to start, try browsing existing issues. Our projects use custom GitHub issue labels for status, version, type of request, etc., but we recommend looking at any issues labeled “good first issue” first. 
+During the PR process, expect that there will be some back-and-forth. Please try to respond to comments in a timely fashion, and if you don't want to continue with the PR, let us know. 
 
+We use the [Vale](https://github.com/errata-ai/vale) linter to ensure that our documentation adheres to the [OpenSearch Project Style Guidelines](STYLE_GUIDE.md). Addressing Vale comments on the PR expedites the review process. You can also install Vale locally so you can address the comments before creating a PR. For more information, see [Style linting](README#style-linting).
 
-## Security issue notifications
+If we accept the PR, we will merge your change and usually take care of backporting it to appropriate branches ourselves.
 
-If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue.
 
+## Getting help
 
-## Licensing
+For help with any step in the contributing process, please reach out to one of the [points of contact](README#points-of-contact).
 
-See the [LICENSE](LICENSE) file for our project's licensing. 

README.md

@@ -4,33 +4,9 @@
 
 The documentation repository contains the documentation for OpenSearch, the search, analytics, and visualization suite with advanced security, alerting, SQL support, automated index management, deep performance analysis, and more. You can find the rendered documentation at [opensearch.org/docs](https://opensearch.org/docs).
 
-
-## How you can help
-
-Community contributions remain essential in keeping this documentation comprehensive, useful, well-organized, and up-to-date. If you are interested in contributing, please see the [Contribution](https://github.com/opensearch-project/documentation-website/blob/main/CONTRIBUTING.md) file.
-
-
-## Points of contact
-
-If you encounter problems or have questions when contributing to the documentation, these people can help:
-
-- [cwillum](https://github.com/cwillum)
-- [hdhalter](https://github.com/hdhalter)
-- [kolchfa-aws](https://github.com/kolchfa-aws)
-- [Naarcha-AWS](https://github.com/Naarcha-AWS)
-- [vagimeli](https://github.com/vagimeli)
-
-
 ## How the website works
 
-This repository contains [Markdown](https://guides.github.com/features/mastering-markdown/) files organized into Jekyll "collections" (e.g., `_search-plugins`, `_opensearch`, etc.). Each Markdown file correlates with one page on the website.
-
-Using plain text on GitHub has many advantages:
-
-- Everything is free, open source, and works on every operating system. Use your favorite text editor, Ruby, Jekyll, and Git.
-- Markdown is easy to learn and looks good in side-by-side diffs.
-- The workflow is no different than contributing code. Make your changes, build locally to check your work, and submit a pull request. Reviewers check the PR before merging.
-- Alternatives like wikis and WordPress are full web applications that require databases and ongoing maintenance. They also have inferior versioning and content review processes compared to Git. Static websites, such as the ones Jekyll produces, are faster, more secure, and more stable.
+This repository contains [Markdown](https://guides.github.com/features/mastering-markdown/) files organized into Jekyll _collections_ (for example, `_api-reference` or `_dashboards`). Each Markdown file corresponds to one page on the website.
 
 In addition to the content for a given page, each Markdown file contains some Jekyll [front matter](https://jekyllrb.com/docs/front-matter/). Front matter looks like this:
 
@@ -44,82 +20,14 @@ has_children: false
 ---
 ```
 
-If you want to reorganize content or add new pages, keep an eye on `has_children`, `parent`, and `nav_order`, which define the hierarchy and order of pages in the lefthand navigation. For more information, see the documentation for [our upstream Jekyll theme](https://pmarsceill.github.io/just-the-docs/docs/navigation-structure/).
-
-
-## Contribute content
-
-There are a few ways to contribute content, depending on the magnitude of the change.
-
-- [Minor changes](#minor-changes)
-- [Major changes](#major-changes)
-- [Create an issue](https://github.com/opensearch-project/documentation-website/issues)
-
-
-### Minor changes
-
-If you want to add a few paragraphs across multiple files and are comfortable with Git, try this approach:
-
-1. Fork this repository.
-
-1. Download [GitHub Desktop](https://desktop.github.com), install it, and clone your fork.
-
-1. Navigate to the repository root.
-
-1. Create a new branch.
-
-1. Edit the Markdown files in `/docs`.
-
-1. Commit, [sign off](https://github.com/src-d/guide/blob/9171d013c648236c39faabcad8598be3c0cf8f56/developer-community/fix-DCO.md#how-to-prevent-missing-sign-offs-in-the-future), push your changes to your fork, and submit a pull request.
+If you want to reorganize content or add new pages, keep an eye on `has_children`, `parent`, and `nav_order`, which define the hierarchy and order of pages in the left navigation. For more information, see the documentation for [our upstream Jekyll theme](https://pmarsceill.github.io/just-the-docs/docs/navigation-structure/).
 
 
-### Major changes
-
-If you're making major changes to the documentation and need to see the rendered HTML before submitting a pull request, here's how to make the changes and view them locally:
-
-1. Fork this repository.
-
-1. Download [GitHub Desktop](https://desktop.github.com), install it, and clone your fork.
-
-1. Navigate to the repository root.
-
-1. Install [Ruby](https://www.ruby-lang.org/en/) if you don't already have it. We recommend [RVM](https://rvm.io/), but use whatever method you prefer:
-
-   ```
-   curl -sSL https://get.rvm.io | bash -s stable
-   rvm install 2.6
-   ruby -v
-   ```
-
-1. Install [Jekyll](https://jekyllrb.com/) if you don't already have it:
-
-   ```
-   gem install bundler jekyll
-   ```
-
-1. Install dependencies:
-
-   ```
-   bundle install
-   ```
-
-1. Build:
-
-   ```
-   sh build.sh    
-   ```
-
-1. If the build script doesn't automatically open your web browser (it should), open [http://localhost:4000/docs/](http://localhost:4000/docs/).
-
-1. Create a new branch.  
-
-1. Edit the Markdown files in each collection (e.g. `_security/`).
-
-   If you're a web developer, you can customize `_layouts/default.html` and `_sass/custom/custom.scss`.
+## How you can help
 
-1. When you save a file, marvel as Jekyll automatically rebuilds the site and refreshes your web browser. This process can take anywhere from 10-30 seconds.
+Community contributions remain essential in keeping this documentation comprehensive, useful, well-organized, and up-to-date. 
 
-1. When you're happy with how everything looks, commit, [sign off](https://github.com/src-d/guide/blob/9171d013c648236c39faabcad8598be3c0cf8f56/developer-community/fix-DCO.md#how-to-prevent-missing-sign-offs-in-the-future), push your changes to your fork, and submit a pull request.
+If you are interested in submitting an issue or contributing content, see [CONTRIBUTING](https://github.com/opensearch-project/documentation-website/blob/main/CONTRIBUTING.md).
 
 
 ## Writing tips
@@ -128,6 +36,8 @@ The OpenSearch team released [style guidelines](https://github.com/opensearch-pr
 
 We also provide guidelines on terminology. For a list of OpenSearch terms, see [Terms](https://github.com/opensearch-project/documentation-website/blob/main/TERMS.md).
 
+If you are contributing API content, see the [API Style Guide](API_STYLE_GUIDE) for API documentation guidelines.
+
 
 ## Formatting documentation
 
@@ -143,19 +53,31 @@ We use the [Vale](https://github.com/errata-ai/vale) linter to ensure that our d
 
 Optionally, you can install the [Vale VSCode](https://github.com/chrischinchilla/vale-vscode) extension that integrates Vale with Visual Studio Code. By default, only _errors_ and _warnings_ are underlined. To change the minimum alert level to include _suggestions_, go to **Vale VSCode** > **Extension Settings** and select **suggestion** in the **Vale > Vale CLI: Min Alert Level** dropdown list. 
 
+
+## Points of contact
+
+If you encounter problems or have questions when contributing to the documentation, these people can help:
+
+- [cwillum](https://github.com/cwillum)
+- [hdhalter](https://github.com/hdhalter)
+- [kolchfa-aws](https://github.com/kolchfa-aws)
+- [Naarcha-AWS](https://github.com/Naarcha-AWS)
+- [vagimeli](https://github.com/vagimeli)
+
+
 ## Code of conduct
 
 This project has adopted an [Open Source Code of Conduct](https://opensearch.org/codeofconduct.html).
 
 
 ## Security
 
-See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
+If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security using our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public GitHub issue.
 
 
 ## License
 
-This project is licensed under the Apache-2.0 License.
+This project is licensed under the [Apache 2.0 License](LICENSE).
 
 
 ## Copyright