Revise and consolidate contrib guidance for 1st-timers; add note about AI (#8517)

Author: chalin

content/en/docs/contributing/_index.md

@@ -3,9 +3,43 @@ title: Contributing
 aliases: [/docs/contribution-guidelines]
 sidebar_root_for: self
 weight: 980
+cascade:
+  chooseAnIssueAtYourLevel: |
+    Make sure to [choose an issue] that matches your level of **experience** and
+    **understanding** of OpenTelemetry. Avoid overreaching your capabilities.
+  _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
 ---
 
-Thanks for your interest in contributing to the OpenTelemetry docs and website.
+{{% alert title="Thank you for your interest!" color=success %}}
+
+Thank you for your interest in contributing to the OpenTelemetry docs and
+website.
+
+{{% /alert %}}
+
+## <i class='far fa-exclamation-triangle text-warning '></i> First time contributing? {#first-time-contributing}
+
+- **[Choose an issue]** with the following labels:
+  - [Good first issue](<{{% param _issue %}}%22good+first+issue%22>)
+  - [Help wanted](<{{% param _issue %}}%3A%22help+wanted%22>)
+
+  {{% alert title="We do not assign issues" color="warning" %}}
+
+  We **_do not_ assign issues** to those who have not already made contributions
+  to the [OpenTelemetry organization][org], unless part of a confirmed
+  mentorship or onboarding process.
+
+  [org]: https://github.com/open-telemetry
+
+  {{% /alert %}}
+
+- {{% param chooseAnIssueAtYourLevel %}}
+
+- Want to work other issues or larger changes? [Discuss it with maintainers
+  first][].
+
+[discuss it with maintainers first]: issues/#fixing-an-existing-issue
 
 ## Jump right in!
 
@@ -20,17 +54,8 @@ What do you want to do?
   - [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:
@@ -48,6 +73,7 @@ the community [OpenTelemetry New Contributor Guide]. Every [OTel
 repository][org] for language implementations, the Collector, and conventions
 have their own project-specific contributing guides.
 
+[choose an issue]: issues/#fixing-an-existing-issue
+[issues]: issues/
 [OpenTelemetry New Contributor Guide]:
   https://github.com/open-telemetry/community/blob/main/guides/contributor
-[org]: https://github.com/open-telemetry

content/en/docs/contributing/issues.md

@@ -5,50 +5,20 @@ description:
   improvement.
 weight: 10
 _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
 cSpell:ignore: prepopulated
 ---
 
-<style>
-  /* Force all list to be compact. */
-  li > p {
-    margin-bottom: 0;
-  }
-
-  /* Style "first time" alert */
-  .alert--first-timer {
-    margin: 0.5rem 0 !important;
-
-    > blockquote {
-      margin-top: 1rem;
-      margin-bottom: 0;
-      border-left-color: var(--bs-warning);
-      background-color: var(--bs-danger-bg-subtle);
-      > *:last-child {
-        margin-bottom: 0;
-      }
-    }
-  }
-</style>
-
 ## Fixing an existing issue
 
-One of the best ways to help make OTel docs better is to fix an existing issue.
+One of the best ways to help improve the documentation 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. <a name="first-issue"></a>
-   {{% alert title="First time contributing?" color="primary alert--first-timer" %}}
-
-   Select an issue with the following labels:
-   - [Good first issue](<{{% param _issue %}}%22good+first+issue%22>)
-   - [Help wanted](<{{% param _issue %}}%3A%22help+wanted%22>)
-
-   > **NOTE**: we **_do not_ assign issues** to those who have not already made
-   > contributions to the [OpenTelemetry organization][org], unless part of a
-   > mentorship or onboarding process.
-   >
-   > [org]: https://github.com/open-telemetry
+2. Select an issue that you would like to work on.
+
+   {{% alert color="warning" %}}
+
+   {{% param chooseAnIssueAtYourLevel %}}
 
    {{% /alert %}}
 

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

@@ -15,23 +15,24 @@ To contribute new or improve existing documentation, submit a [pull request][PR]
 - Otherwise, see [Work from a local fork](#fork-the-repo) to learn how to make
   changes in your own local development environment.
 
-{{% alert title="Contributor License Agreement (CLA)" color=warning %}}
+## Generative AI contribution policy {#using-ai}
 
-All contributors are required to [sign a Contributor License Agreement
-(CLA)][CLA] before changes can be reviewed and merged.
+{{% alert color="warning" %}}
 
-[CLA]: ../prerequisites/#cla
+Generative AI is allowed, but **you are responsible** for **reviewing and
+_validating_** all AI-generated content — if you don't understand it,
+don't submit it!
+
+This is especially important for [first-time contributors]. For details, see our
+[Generative AI Contribution Policy][].
 
 {{% /alert %}}
 
-{{% alert title="Tip: Draft status" %}}
+[first-time contributors]: ../#first-time-contributing
+[Generative AI Contribution Policy]:
+  https://github.com/open-telemetry/community/blob/main/policies/genai.md
 
-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 %}}
+## How to contribute
 
 The following figure illustrates how to contribute new documentation.
 
@@ -43,7 +44,7 @@ flowchart LR
        B[Fork the repo in GitHub] --- C[Write docs in markdown<br>and build site with Hugo]
        C --- D[Push source to the fork]
        D --- E[Open a pull request]
-       E --- F[Sign the CNCF CLA]
+       E --- F[Sign the <a href="../prerequisites/#cla">CNCF CLA</a>]
     end
 
 classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
@@ -56,6 +57,15 @@ class first,second white
 
 _Figure 1. Contributing new content._
 
+{{% alert title="Tip: 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 %}}
+
 ## Using GitHub {#changes-using-github}
 
 ### Edit and submit changes from your browser {#page-edit-from-browser}

static/refcache.json

@@ -6539,6 +6539,10 @@
     "StatusCode": 206,
     "LastSeen": "2025-11-13T09:47:02.382315365Z"
   },
+  "https://github.com/open-telemetry/community/blob/main/policies/genai.md": {
+    "StatusCode": 206,
+    "LastSeen": "2025-11-26T13:27:01.195911-05:00"
+  },
   "https://github.com/open-telemetry/community/blob/main/project-management.md": {
     "StatusCode": 206,
     "LastSeen": "2025-11-20T09:40:33.72041867Z"