Add style guide and basic contribution section

.htmltest.yml

@@ -8,6 +8,7 @@ TestFilesConcurrently: true
 IgnoreDirs:
   - ^blog/(\d+/)?page/\d+
 IgnoreInternalURLs: # list of paths
+  - /docs/contribution-guidelines/
 IgnoreURLs: # list of regexs of paths or URLs to be ignored
   - ^/docs/instrumentation/\w+/(api|examples)/$
   - ^/docs/instrumentation/net/(metrics-api|traces-api)/

CONTRIBUTING.md

@@ -1,46 +1,53 @@
 # Contributing to OpenTelemetry.io
 
-Thanks for your interest in contributing to
-[OpenTelemetry.io](https://opentelemetry.io/)! Here are a few general guidelines
-on contributing and reporting bugs that we ask you to review. Following these
-guidelines helps to communicate that you respect the time of the contributors
-managing and developing this open source project. In return, they should
-reciprocate that respect in addressing your issue, assessing changes, and
-helping you finalize your pull requests. In that spirit of mutual respect, we
-endeavor to review incoming issues and pull requests, and will close any
-lingering issues or pull requests after long times of inactivity.
-
-Note that all of your interactions in the project are subject to our
-[Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md).
-This includes creation of issues or pull requests, commenting on issues or pull
-requests, and extends to all interactions in any real-time space e.g., Slack,
-Discord, etc.
-
-Also review the general
+**Thanks for your interest in contributing to
+[OpenTelemetry.io](https://opentelemetry.io/)!**
+
+Follow these guidelines helps to communicate that you respect the time of the
+contributors managing and developing this open source project. In return,
+maintainers and approvers should reciprocate that respect in addressing your
+issue, assessing changes, and helping you finalize your pull requests. In that
+spirit of mutual respect, we endeavor to review incoming issues and pull
+requests, and will close any lingering issues or pull requests after long times
+of inactivity.
+
+## Before you get started
+
+### Code of Conduct
+
+All of your interactions in this project are subject to our
+[Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md)
+. This includes the creation of issues or pull requests, commenting on issues or
+pull requests, and extends to all interactions in any real-time space, for
+example Slack, Discord, and so on.
+
+### Contributor License Agreement
+
+Review the general
 [OpenTelemetry Contributor Guide](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md),
-that will provide additional details, especially that you need to sign a
+as it provides additional details, especially that you need to sign a
 Contributor License Agreement (CLA) before you can contribute.
 
-## Found a security issue?
+### Found a security issue?
 
-If you discover a security issue, **do not** report it through GitHub. Instead,
-follow the steps in our
-[Security Policy](https://github.com/open-telemetry/opentelemetry.io/security/policy).
+If you discover a security issue, read the
+[Security Policy](https://github.com/open-telemetry/opentelemetry.io/security/policy)
+before opening an issue.
 
-## Found a problem?
+### Found a problem?
 
-If you find a problem with the content of this repository, or you would like to
-request an enhancement, [create an issue][new-issue].
+If you find a bug or a problem with the content of this repository, or you would
+like to request an enhancement, [create an issue][new-issue].
 
-Before reporting a new issue, please ensure that the issue was not already
-reported or fixed by searching through our
+Before reporting a new issue, make sure that the issue was not already reported
+or fixed by searching through our
 [issues list](https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc).
 
-When creating a new issue, include a short meaningful title and clear a
-description, as much relevant information as possible, and, if possible, a test
-case.
+When creating a new issue, include a short, meaningful title and a clear
+description. Add as much relevant information as you can, and, if possible, a
+test case.
 
-## Want to work on an existing issue?
+### Want to work on an existing issue?
 
 This is the best way how you can help us to make our documentation better! Take
 a look at issues tagged with
@@ -59,64 +66,11 @@ non-community members who have already made contributions to the [OpenTelemetry
 organization][org]. After confirmation through a maintainer, plan to provide a
 PR shortly or let maintainers now if you run into any blockers.
 
-## Sending Pull Requests
-
-Enhancements and fixes to the website are most welcome!
-
-Before sending a new [pull request][pr] (PR), take a look at existing
-[pull requests](https://github.com/open-telemetry/opentelemetry.io/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc)
-and
-[issues](https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc)
-to see if the proposed change or fix has been discussed in the past, or if the
-change was already implemented but not yet released.
-
-### Quick fixes
-
-For small changes to a single file, you can edit directly in GitHub by clicking
-**Edit this file** button. After forking the repository, follow the instructions
-in [Editing files][].
-
-However, formatting may still be needed, like reducing line lengths in the
-edited file. The options for fixing formatting are:
-
-- Checking out the project and running the CLI scripts mentioned in
-  [Submitting a change](#submitting-a-change).
-- Commenting `/fix:format` on your pull request to trigger an automated script.
-  This requires a unique branch name, which can be edited under _View all
-  branches_ in your fork.
-
-For larger fixes, follow the
-[instructions to setup a development environment](#development) below.
-
-### PR Guidelines
-
-Before a PR gets merged, it will sometimes require a few iterations of
-review-and-edit. To help us and yourself make this process as easy as possible,
-we ask that adhere to the following:
-
-- If your PR isn't a [quick fix](#quick-fixes), then **work from a fork**: Click
-  the [Fork](https://github.com/open-telemetry/opentelemetry.io/fork) button at
-  the top of the repository and clone the fork locally. When you are ready,
-  raise a PR with the upstream repository.
-- **Do not work from the `main`** branch of your fork, but create a PR-specific
-  branch.
-- Ensure that maintainers are
-  [allowed to apply changes to your pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork).
+## Contributor's guide
 
-### Merge requirements
-
-- No “changes requested” reviews by approvers, maintainers, technical committee
-  members, or subject matter experts
-- No unresolved conversations
-- Approved by at least one approver
-- No failing PR checks
-- PR branch is up-to-date with the base branch
-
-> **Important**
->
-> Do not worry too much about failing PR checks! Community members will help you
-> to get them fixed, by either providing you with instructions how to fix them
-> or by fixing them on your behave.
+To learn how to contribute fixes and new content to this project, read the
+[Contributor's guide](/content/en/docs/contributing), which includes a style
+guide and useful information on the review process.
 
 ## Development
 
@@ -219,24 +173,6 @@ The website is built from the following content:
 [content-modules]:
   https://github.com/open-telemetry/opentelemetry.io/tree/main/content-modules
 
-### Submitting a change
-
-Before submitting a change to the repository, run the following command and
-address any reported issues. Also commit any files changed by the `fix` script:
-
-```sh
-npm run test-and-fix
-```
-
-To separately test and fix issues with your files, run:
-
-```sh
-npm run test # checks but does not update any files
-npm run fix  # may update files
-```
-
-To list available NPM scripts, run `npm run`.
-
 ### Submodule changes
 
 If you change any content inside of a [content-modules][] submodule, then you'll
@@ -255,17 +191,6 @@ submodule itself.
 > You'll also need to `git fetch --unshallow` the submodule before you can
 > submit a PR. Alternatively, set `DEPTH=100` and re-fetch submodules.
 
-### Site deploys and PR previews
-
-If you submit a PR, Netlify will create a [deploy preview][] so that you can
-review your changes. Once your PR is merged, Netlify deploys the updated site to
-the production server.
-
-> **Note**: PR previews include _draft pages_, but production builds do not.
-
-To see deploy logs and more, visit project's [dashboard][] -- Netlify login
-required.
-
 ## Approver and Maintainer practices
 
 This last section includes guidelines and some common practices used by
@@ -302,18 +227,12 @@ approvers and maintainers while doing code reviews:
 [.nvmrc]: .nvmrc
 [clone]:
   https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository
-[dashboard]: https://app.netlify.com/sites/opentelemetry/overview
-[deploy preview]:
-  https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/
-[editing files]:
-  https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files
 [fork]: https://docs.github.com/en/get-started/quickstart/fork-a-repo
 [gitpod.io]: https://gitpod.io
 [gitpod.io/workspaces]: https://gitpod.io/workspaces
 [hugo]: https://gohugo.io
 [localhost:1313]: http://localhost:1313
 [localhost:8888]: http://localhost:8888
-[netlify]: https://netlify.com
 [new-issue]:
   https://github.com/open-telemetry/opentelemetry.io/issues/new/choose
 [nodejs-rel]: https://nodejs.org/en/about/previous-releases
@@ -323,5 +242,3 @@ approvers and maintainers while doing code reviews:
   https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating
 [nvm-windows]: https://github.com/coreybutler/nvm-windows
 [org]: https://github.com/open-telemetry
-[pr]:
-  https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests

README.md

@@ -1,78 +1,42 @@
 # <img src="https://opentelemetry.io/img/logos/opentelemetry-logo-nav.png" alt="OTel logo" width="45"> OpenTelemetry.io
 
 This is the source repository for the [OpenTelemetry][] website, project
-documentation and blog. The site is [built][contributing.md] using [Hugo][] and
-hosted on [Netlify][].
+documentation, and blog. The site is [built][contributing.md] using [Hugo][] and
+is hosted on [Netlify][].
 
 ## Get involved
 
+To learn how to contribute fixes and new content to this project, read the
+[Contributor's guide](/content/en/docs/contributing), which includes a style
+guide and useful information on the review process.
+
 If you are new to OpenTelemetry and just get started with it, you are in a
 perfect position to help us get better: the website and documentation is the
 entry point for newcomers like you, so if something is unclear or something is
-missing [let us know][]!
-
-Read on to learn about other ways on how you can help.
-
-## Adding a project to the OpenTelemetry [Registry]
-
-For details, see [Adding to the registry][].
-
-## Submitting a blog post
-
-You can submit a blog post either by forking this repository and writing it
-locally or by using the GitHub UI. In both cases we ask you to follow the
-instructions provided by the [blog post template](archetypes/blog.md).
-
-**Note**: Before writing a blog post, please ask yourself, if your content also
-might be a good addition to the documentation. If the answer is yes, create a
-new issue/PR with your content to get it added to the docs.
+missing [let us know][].
 
-### Fork & Write locally
+### Submit a blog post
 
-Follow the [setup instructions][contributing.md] then, to create a skeletal blog
-post, run the following command from the repository root:
+For guidance on how to write and submit a blog post, see
+[Submit a blog post](/content/en/docs/contributing/blog).
 
-```sh
-npx hugo new content/en/blog/2023/short-name-for-post.md
-```
+### Add a project to the OpenTelemetry [Registry]
 
-If your post will have images or other assets, instead run:
-
-```sh
-npx hugo new content/en/blog/2023/short-name-for-post/index.md
-```
-
-Edit the markdown file at the path you provided in the previous command. The
-file is initialized from the blog-post starter under [archetypes](archetypes).
-
-Put assets, if any, like images into the folder created.
-
-Once your post is ready, submit it through a [pull request][].
-
-### Using the GitHub UI
-
-- Go to the [blog post template](archetypes/blog.md) and click on
-  `Copy raw content` at the top right of the menu.
-- [Create a new file](https://github.com/open-telemetry/opentelemetry.io/new/main).
-- Paste the content from the template.
-- Name your file, e.g.
-  `content/en/blog/2022/short-name-for-your-blog-post/index.md`
-- Start editing the markdown file.
-- Once your post is ready click on `Propose changes` at the bottom.
+For details on how to add a project to the OpenTelemetry Registry, see [Adding
+to the registry][].
 
 ## Contributing
 
-See [CONTRIBUTING.md][].
-
 We have curated some issues with the tags [help wanted][] and [good first
-issue][]. This should allow you to quickly find a place to contribute
+issue][]. This should allow you to quickly find a place to contribute. See
+[CONTRIBUTING.md][] for more information.
 
-We (OTel Comms SIG) meet every two weeks on Monday at 9:00 PT. Check out the
+We, the OTel Comms SIG, meet every two weeks on Monday at 9:00 PT. Check out the
 [OpenTelemetry community calendar][] for the Zoom link and any updates to this
 schedule.
 
 Meeting notes are available as a public [Google doc][]. If you have trouble
-accessing the doc, please get in touch on [Slack][].
+accessing the doc, get in touch on [Slack][].
 
 Here is a list of community roles with current and previous members:
 
@@ -121,8 +85,6 @@ already contributed][contributors]!
 [hugo]: https://gohugo.io
 [netlify]: https://netlify.com
 [opentelemetry]: https://opentelemetry.io
-[pull request]:
-  https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
 [registry]: https://opentelemetry.io/ecosystem/registry/
 [opentelemetry community calendar]:
   https://calendar.google.com/calendar/embed?src=google.com_b79e3e90j7bbsa2n2p5an5lf60%40group.calendar.google.com