Contributing: improved guidance for quick-fixers, mentees, and more (o…

…pen-telemetry#5266)

.htmltest.yml

@@ -8,6 +8,8 @@ CheckMailto: false
 TestFilesConcurrently: true
 IgnoreDirs:
   - ^blog/(\d+/)?page/\d+
+  # TODO drop after https://github.com/open-telemetry/opentelemetry.io/issues/5267 is fixed:
+  - zh/docs/contributing/pr-checks
 IgnoreInternalURLs: # list of paths
 IgnoreURLs: # list of regexs of paths or URLs to be ignored
   - ^((/..)?/docs/languages/\w+|\.\.)/(api|examples|registry)/$

content/en/docs/contributing/_index.md

@@ -1,29 +1,52 @@
 ---
 title: Contributing
-description: Learn how to contribute to OpenTelemetry documentation.
 aliases: [/docs/contribution-guidelines]
 weight: 980
 ---
 
+Thanks for your interest in contributing to the OpenTelemetry docs and website.
+
+## Jump right in!
+
+What do you want to do?
+
+- Correct a **typo or other quick fixes**, see
+  [Submitting content using GitHub](pull-requests/#changes-using-github)
+- For more significant contributions, read the pages in this section starting
+  with:
+  - [Prerequisites]
+  - [Issues]
+  - [Submitting content]
+
+[Prerequisites]: prerequisites/
+[Issues]: issues/
+[Submitting content]: pull-requests/
+
+{{% alert title="<i class='far fa-exclamation-triangle'></i> First time contributing? " %}}
+
+Eager first-time contributors, see
+[Fixing an existing issue](issues/#fixing-an-existing-issue) for important
+guidance.
+
+{{% /alert %}}
+
+## What can I contribute to?
+
 OpenTelemetry documentation contributors:
 
-- Improve existing content.
-- Create new content.
-- Update the OpenTelemetry Registry.
-- Improve the code that builds the site.
+- Improve existing or create new content
+- [Submit a blog post](blog/) or case study
+- Add to or update the [OpenTelemetry Registry](/ecosystem/registry/)
+- Improve the code that builds the site
 
-The following guides describe how to contribute to OpenTelemetry documentation.
+The pages in this section describe how to contribute to OpenTelemetry
+**documentation**.
 
 For guidance on how to contribute to the OpenTelemetry project in general, see
-the
-[OpenTelemetry Contributor Guide](https://github.com/open-telemetry/community/blob/main/guides/contributor/README.md)
-, which provides details on the Contributor License Agreement and the Code of
-Conduct. Every language implementation, Collector, and conventions
-[repository](https://github.com/open-telemetry/) has its own specific
+the community [OpenTelemetry New Contributor Guide]. Every [OTel repository][org]
+for language implementations, the Collector, and conventions have their own project-specific
 contributing guides.
 
-## Other ways to contribute
-
-- Visit the [OpenTelemetry community site](/community/).
-- Add your application to the [Registry](/ecosystem).
-- Submit a [blog post or case study](/docs/contributing/blog/).
+[OpenTelemetry New Contributor Guide]:
+  https://github.com/open-telemetry/community/blob/main/guides/contributor
+[org]: https://github.com/open-telemetry

content/en/docs/contributing/development.md

@@ -1,5 +1,6 @@
 ---
-title: Development
+title: Development setup and commands to build, serve, and more
+linkTitle: Dev setup and more
 description:
   Learn how to set up a development environment for the opentelemetry.io site.
 weight: 60

content/en/docs/contributing/issues.md

@@ -1,10 +1,54 @@
 ---
-title: Reporting an issue
-description: How to report a bug, a security issue, or a potential improvement.
-weight: 50
+title: Issues
+description:
+  How to fix an existing issue, or report a bug, security risk, or potential
+  improvement.
+weight: 10
 cSpell:ignore: prepopulated
+_issues: https://github.com/open-telemetry/opentelemetry.io/issues
+_issue: https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A
 ---
 
+## Fixing an existing issue
+
+One of the best ways to help make OTel docs better is to fix an existing issue.
+
+1. Browse through the list of [issues]({{% param _issues %}}).
+2. Select an issue that you would like to work on, ideally one that you can fix
+   in a short amount of time.
+
+   <!-- prettier-ignore -->
+   <a name="first-issue"></a>
+   {{% alert title="First time contributing? " %}}
+
+   Select an issue with the following labels:
+
+   - [Good first issue]
+   - [Help wanted]
+
+   <!-- prettier-ignore -->
+   > **NOTE**: we **_do not_ assign issues** to those who
+   > have not already made contributions to the [OpenTelemetry
+   > organization][org].
+   {.mt-3}
+
+   <!-- prettier-ignore -->
+   [good first issue]: {{% param _issue %}}%22good+first+issue%22
+   [help wanted]: {{% param _issue %}}%3A%22help+wanted%22
+   [org]: https://github.com/open-telemetry
+
+   {{% /alert %}}
+
+3. Read through the issue comments, if any.
+4. Ask maintainers if this issue is still relevant, and ask any questions you
+   need for clarification by posting comments over the issue.
+5. Share your intention to work on the issue by adding add a comment to this
+   effect.
+6. Work on fixing the issue. Let maintainers now if you run into any problems.
+7. When ready, [submit your work through a pull request](../pull-requests) (PR).
+
+## Reporting an issue
+
 If you notice an error or want to suggest improvements to existing content, open
 an issue.
 

content/en/docs/contributing/pr-checks.md

@@ -18,8 +18,8 @@ a set of checks are executed. The PR checks verify that...
 
 {{% alert title="Note" color="primary" %}}
 
-If any of the PR checks fails, please try to
-[fix content issues automatically](/docs/contributing/new-content/#fix-content-issues-automatically)
+If any of the PR checks fails, try to
+[fix content issues automatically](../pull-requests/#fix-content-issues-automatically)
 first by running `npm run fix:all` on your machine.
 
 Additionally, you can comment `/fix:all` on your Pull Request. This will make
@@ -33,8 +33,7 @@ can recover from a failed state.
 
 ## Easy CLA
 
-This check fails if you haven't
-[signed the CLA](/docs/contributing/requirements/#sign-the-cla).
+This check fails if you haven't [signed the CLA](../prerequisites/#cla).
 
 ## Netlify deployment
 
@@ -43,17 +42,17 @@ more information.
 
 ## Style checks
 
-To make sure that contributions follow our
-[style guide](/docs/contributing/style-guide) we have implemented a set of
-checks that verify style guide rules and fail l if they find any issues.
+To make sure that contributions follow our [style guide](../style-guide/) we
+have implemented a set of checks that verify style guide rules and fail l if
+they find any issues.
 
 The following list describes current checks and what you can do to fix related
 errors:
 
 ### TEXT linter
 
 This check verifies that
-[OpenTelemetry-specific terms and words are used consistently across the site](/docs/contributing/style-guide#opentelemetryio-word-list).
+[OpenTelemetry-specific terms and words are used consistently across the site](../style-guide/#opentelemetryio-word-list).
 
 If any issues are found, annotations are added to your files in the
 `files changed` view of your PR. Fix those to turn the check green. As an
@@ -63,15 +62,15 @@ issues. Run `npm run check:text` again and manually fix the remaining issues.
 ### MARKDOWN linter
 
 This check verifies that
-[standards and consistency for Markdown files are enforced](/docs/contributing/style-guide#markdown-standards).
+[standards and consistency for Markdown files are enforced](../style-guide/#markdown-standards).
 
 If any issues are found, run `npm:run format` to fix most issues. For more
 complex issues, run `npm run check:markdown` and apply the suggested changes.
 
 ### SPELLING check
 
 This check verifies that
-[all words are spelled correctly](/docs/contributing/style-guide#spell-checking).
+[all words are spelled correctly](../style-guide/#spell-checking).
 
 ### CSPELL:IGNORE check
 
@@ -83,15 +82,15 @@ new commit.
 ### FILENAME check
 
 This check verifies that all
-[files are formatted by prettier](/docs/contributing/style-guide#file-format).
+[files are formatted by prettier](../style-guide/#file-format).
 
 If this check fails, run `npm fix:format` locally and push the changes in a new
 commit.
 
 ### FILE FORMAT
 
 This check verifies that all
-[file names are in kebab-case](/docs/contributing/style-guide#file-names).
+[file names are in kebab-case](../style-guide/#file-names).
 
 If this check fails, run `npm fix:filenames` locally and push the changes in a
 new commit.

content/en/docs/contributing/prerequisites.md

@@ -0,0 +1,43 @@
+---
+title: Prerequisites
+description:
+  To contribute, you need to be familiar with the following techs and tools.
+aliases: [requirements]
+weight: 1
+---
+
+To contribute to this repository, you need to be familiar with the following
+techs and tools:
+
+- [git](https://git-scm.com/)
+- [GitHub](https://github.com/)
+- Markdown ([CommonMark](https://commonmark.org/))
+- YAML
+
+For technical details concerning how the documentation is built and tested
+locally, see [Development](../development).
+
+## Sign the CNCF CLA {#cla}
+
+All OpenTelemetry contributors must sign the Linux Foundation [Contributor
+License Agreement (CLA)][CLA].
+
+Pull requests from contributors who haven't signed the CLA fail the automated
+tests. The name and email you provide must match those found in your
+`git config`, and your git name and email must match those used for the CNCF
+CLA.
+
+## Code of conduct
+
+All OpenTelemetry contributors are bound by the [CNCF Community Code of
+Conduct][CoC].
+
+## Community guidelines
+
+For general OpenTelemetry community guidelines, including roles and
+expectations, see [OpenTelemetry New Contributor Guide][NCG]
+
+[CLA]: https://docs.linuxfoundation.org/lfx/easycla/contributors
+[CoC]: https://github.com/cncf/foundation/blob/main/code-of-conduct.md
+[NCG]:
+  https://github.com/open-telemetry/community/blob/main/guides/contributor/README.md

content/en/docs/contributing/new-content.md → content/en/docs/contributing/pull-requests.md

@@ -1,22 +1,26 @@
 ---
-title: Add new content
-description: Learn how to add new content using GitHub UI or a local fork.
-weight: 2
+title: Submitting content
+description:
+  Learn how to submit new or changed content using the GitHub UI or a local
+  fork.
+aliases: [new-content]
+weight: 15
 ---
 
-To contribute new content pages or improve existing content pages, open a pull
-request (PR):
+To contribute new or improve existing documentation content, submit a [pull
+request][PR] (PR):
 
-- If your change is small, or you're unfamiliar with Git, read
+- If your change is small, or you're unfamiliar with Git, see
   [Changes using GitHub](#changes-using-github) to learn how to edit a page.
-- If your changes are large, read [Work from a local fork](#fork-the-repo) to
+- If your changes are large, see [Work from a local fork](#fork-the-repo) to
   learn how to make changes locally on your computer.
 
-{{% alert title="Tip" %}}
+{{% alert title="Tip: Draft status" %}}
 
-Turn your pull request into a draft to signal that the content still isn't ready
-for review. Maintainers may still comment or do high-level reviews, though they
-won't review the content in full until you remove the draft status.
+Set the status of your pull request to **Draft** to let maintainers know that
+the content isn't ready for review yet. Maintainers may still comment or do
+high-level reviews, though they won't review the content in full until you
+remove the draft status.
 
 {{% /alert %}}
 
@@ -46,7 +50,17 @@ _Figure 1. Contributing new content._
 ## Changes using GitHub {#changes-using-github}
 
 If you're less experienced with Git workflows, here's an easier method of
-opening a pull request. Figure 2 outlines the steps and the details follow.
+creating and submitting a pull request. Figure 2 outlines the steps and the
+details follow.
+
+{{% alert title="Contributor License Agreement (CLA)" color=warning %}}
+
+All contributors are required to [sign a Contributor License Agreement
+(CLA)][CLA] before changes can be approved and merged.
+
+[CLA]: ../prerequisites/#cla
+
+{{% /alert %}}
 
 ```mermaid
 flowchart LR
@@ -330,8 +344,7 @@ using [Netlify](https://www.netlify.com/).
   the OpenTelemetry website with your changes applied. This is how reviewers
   check your changes.
 
-Other checks might also fail. See the
-[list of all PR checks](/docs/contributing/pr-checks).
+Other checks might also fail. See the [list of all PR checks](../pr-checks).
 
 ### Fix content issues automatically
 
@@ -349,9 +362,8 @@ npm run test    # Checks but does not update any files
 npm run fix:all # May update files
 ```
 
-To list available NPM scripts, run `npm run`. See
-[PR checks](/docs/contributing/pr-checks) for more information on pull request
-checks and how to fix errors automatically.
+To list available NPM scripts, run `npm run`. See [PR checks](../pr-checks) for
+more information on pull request checks and how to fix errors automatically.
 
 ### Preview your changes locally {#preview-locally}
 
@@ -501,3 +513,4 @@ Pull requests are merged when they comply with the following criteria:
 [dashboard]: https://app.netlify.com/sites/opentelemetry/overview
 [deploy preview]:
   https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/
+[PR]: https://docs.github.com/en/pull-requests

content/en/docs/contributing/style-guide.md

@@ -22,8 +22,8 @@ before submitting a
 [pull request](https://docs.github.com/en/get-started/learning-about-github/github-glossary#pull-request)
 (PR), run `npm run fix:all` on your local machine and commit the changes.
 
-If you run into errors or [failed PR checks](/docs/contributing/pr-checks), read
-about our style guide and learn what you can do to fix certain common issues.
+If you run into errors or [failed PR checks](../pr-checks), read about our style
+guide and learn what you can do to fix certain common issues.
 
 {{% /alert %}}