Contribution guidelines v2

arbitrum-docs/for-devs/third-party-docs/contribute.md

@@ -0,0 +1,37 @@
+---
+title: 'Contribute third-party docs'
+description: "Learn how to contribute to Arbitrum's documentation"
+---
+
+import PublicPreviewBannerPartial from '../../partials/_public-preview-banner-partial.md';
+
+<PublicPreviewBannerPartial />
+
+**Third-party docs** are documents that help readers of Arbitrum docs use other products, services, and protocols (like the ones listed in the [Arbitrum portal](https://portal.arbitrum.io/)) with Arbitrum products.
+
+These documents are usually authored by partner teams, but can be authored by anyone. They follow the same general process that [core docs](/for-devs/contribute#add-a-new-core-document) follow, in addition to the following guidelines:
+
+1.  **Eligibility**
+    - Third-party docs are intended to support products listed in the [Arbitrum portal](https://portal.arbitrum.io/), or infrastructure and services that those products use.
+    - To submit your project to the Arbitrum portal, [apply using this Google form](https://docs.google.com/forms/d/e/1FAIpQLSezhBlPgKIKKWgXKUz4MmlJPdHyfmPQlxUtS48HlRoi0e14_Q/viewform).
+2.  **Purpose**
+    - The purpose of our `Third-party docs` sections is to **_meet Arbitrum developer (or user) demand for guidance that helps them use non-Arbitrum products with Arbitrum products_**.
+    - It's _not_ meant to drive traffic to your product (although that may happen); it's meant to solve problems that our readers are actually facing, which are directly related to Arbitrum products.
+3.  **Maintenance expectations**
+    - Offchain Labs can't commit to maintaining third-party docs, but we make it easy for you to maintain them.
+    - Ensure that your document's YAML frontmatter contains a `third_party_content_owner` property, with the Github username of the designated maintainer. This person will be assigned to your document's issues and PRs, and will be expected to resolve them in a timely manner.
+4.  **Organization**
+    - Third-party docs are organized within the `Third-party content` node located at the bottom of each documentation section's sidebar.
+    - This node's content is grouped by third-party product. If/when this becomes unwieldy, we'll begin grouping products by [portal](https://portal.arbitrum.io/) category.
+5.  **Limited document types**
+    - To manage our team's limited capacity, third-party documents must be either **_Quickstarts_**, **_How-tos_**, or **_Concepts_**. See [document types](/for-devs/contribute#document-type-conventions).
+6.  **Incremental contributions: One document at a time, procedures first**
+    - Third-party document PRs should contain at most one new document.
+    - Any given product's first docs contribution should be a **_Quickstart_** or **_How-to_**.
+    - Additional documents will be merged only if we can verify that our readers are deriving value from your initial contribution.
+    - The way that we verify this isn't yet formally established, and it isn't publicly disclosed. Our current approach combines a number of objective and subjective measures.
+7.  **Policy acknowledgment**
+    - Before merging third-party documentation PRs, we ask contributors to acknowledge that they've read, understood, and agree with the following policies:
+      1. **Content ownership**: As the author, you retain ownership of and responsibility for the content you contribute. You're free to use your content in any way you see fit outside of Arbitrum's docs. Remember that when contributing content to our documentation, you must ensure you have the necessary rights to do so, and that the content doesn't infringe on the intellectual property rights of others.
+      2. **License for use**: By contributing your content to our documentation, you grant Offchain Labs a non-exclusive, royalty-free license to use, reproduce, adapt, translate, distribute, and display the content in our documentation. This allows us to integrate your content into our docs and make it available to all users.
+      3. **Right to modify or remove**: Offchain Labs reserves the right to modify or remove third-party content from our documentation at any time. This might be necessary due to a range of reasons, such as content becoming outdated, receiving very low pageviews over an extended period, or misalignment with our guidelines or goals.

arbitrum-docs/partials/_contribute-docs-partial.md

@@ -1,88 +1,48 @@
 import PublicPreviewBannerPartial from '../partials/_public-preview-banner-partial.md';
 
-:::tip Submitting a docs PR?
-
-**Please review this guidance before issuing pull requests** into the [Arbitrum docs repository](https://developer.arbitrum.io/). This guidance helps us **streamline** and **scale** our efforts. Thank you!
-
-:::
-
 <PublicPreviewBannerPartial />
 
 The [`docs.arbitrum.io`](https://docs.arbitrum.io/) docs portal is the **single source of truth** for documentation that supports Offchain Labs' product portfolio. This includes documentation for:
 
-1. [Building dApps](/for-devs/quickstart-solidity-hardhat.md) with Arbitrum's chains.
-2. [Bridging tokens](../getting-started-users.mdx) to Arbitrum's chains.
-3. [Running an Arbitrum node](../node-running/quickstart-running-a-node.md).
-4. [Launching a self-managed chain](../launch-orbit-chain/orbit-quickstart.md) using Arbitrum Orbit.
-5. [Educational materials](../intro) that explain how these technologies work.
+1. [Developers](/for-devs/quickstart-solidity-hardhat.md)
+2. [Users (bridge)](/getting-started-users.mdx)
+3. [Node runners](/node-running/quickstart-running-a-node.md)
+4. [How it works](/intro)
 
 Contributions to each of these content areas are welcome from the entire Ethereum community.
 
-This document provides an overview of the **protocols** and **content conventions** that we use to craft, organize, and publish documentation. Familiarity with [Markdown](https://www.markdownguide.org/basic-syntax/) syntax, Github, and [Docusaurus](https://docusaurus.io/docs) is expected.
-
-## Protocols
-
-The following protocols help us process contributions efficiently:
+This document shows you how to craft, organize, and publish Arbitrum documentation. Familiarity with [Markdown](https://www.markdownguide.org/basic-syntax/) syntax, Github, and [Docusaurus](https://docusaurus.io/docs) is expected.
 
-### New "core docs" protocol
+### Add a new core document
 
-If a document isn't in the `Third-party content` sidebar node, it's a core document.
+If a document isn't in a `Third-party content` sidebar node, it's a **core document**. To contribute a new core doc:
 
-Although Offchain Labs is responsible for producing and maintaining core docs, contributions are welcome from all. To contribute a new core doc:
-
-1.  Begin by creating a branch of the [Arbitrum docs repo](https://github.com/OffchainLabs/arbitrum-docs).
-2.  Issue a `Draft` pull request from your branch into `master`. Pull requests into `master` generate a preview of your changes via a branch-specific Docusaurus deployment; this preview will update as you push commits to your remote branch.
+1.  Begin by creating a branch (internal) or fork (external) of the [Arbitrum docs repo](https://github.com/OffchainLabs/arbitrum-docs).
+2.  Issue a `Draft` pull request into `master`. Pull requests into `master` generate a preview of your changes via a PR-specific Docusaurus deployment; this preview will update as you push commits to your remote.
 3.  Include answers to the following questions in your PR description:
     ```markdown
     1. Audience: Who am I writing for?
     2. Problem: What specific problem are they trying to solve?
     3. Discovery: How are they looking for a solution to this problem? What search terms are they using?
     4. Document type: Which document type is most suitable?
-    5. Validated demand: How do we know that this documentation is actually needed?
-    6. Policy acknowledgment (Third-party docs only): Do you agree to the third-party content policy outlined within "Contribute docs"?
+    5. Policy acknowledgment (Third-party docs only): Do you agree to the third-party content policy outlined within "Contribute docs"?
     ```
 4.  As you craft your contribution, refer to the [document types](#document-type-conventions), [Style guidance](#style-conventions), and other conventions below.
 5.  Mark your PR as `Open` when it's ready for review.
 
-### New "third-party docs" protocol
-
-**Third-party docs** are documents that help readers of Arbitrum docs use other products, services, and protocols (like the ones listed in the [Arbitrum portal](https://portal.arbitrum.io/)) with Arbitrum products. These documents are generally authored by partner teams, but can be authored by anyone.
-
-The protocol for creating new third-party docs is the same as that of [Creating new core documents](#creating-new-third-party-documents), with the following additions:
-
-1.  **Eligibility**
-    - Third-party docs are intended to support products listed in the [Arbitrum portal](https://portal.arbitrum.io/), or infrastructure and services that those products use.
-    - To submit your project to the Arbitrum portal, [apply using this Google form](https://docs.google.com/forms/d/e/1FAIpQLSezhBlPgKIKKWgXKUz4MmlJPdHyfmPQlxUtS48HlRoi0e14_Q/viewform).
-2.  **Purpose**
-    - The purpose of our `Third-party docs` sections is to **_meet Arbitrum developer (or user) demand for guidance that helps them use non-Arbitrum products with Arbitrum products_**.
-    - It's _not_ meant to drive traffic to your product (although that may happen); it's meant to solve problems that our readers are actually facing, which are directly related to Arbitrum products.
-    - Partner products that support Arbitrum products aren't automatically eligible; we need to be able to prove to ourselves that our readers actually need the proposed third-party content.
-3.  **Maintenance expectations**
-    - Offchain Labs can't commit to maintaining third-party docs, but we make it easy for you to maintain them.
-    - Ensure that your document's YAML frontmatter contains a `third_party_content_owner` property, with the Github username of the designated maintainer. This person will be assigned to your document's issues and PRs, and will be expected to resolve them in a timely manner.
-4.  **Organization**
-    - Third-party docs are organized within the `Third-party content` node located at the bottom of each documentation section's sidebar.
-    - This node's content is grouped by third-party product. If/when this becomes unwieldy, we'll begin grouping products by [portal](https://portal.arbitrum.io/) category.
-5.  **Limited document types**
-    - To manage our team's limited capacity, third-party documents must be either **_Quickstarts_**, **_How-tos_**, or **_Concepts_**. See [document types](#document-type-conventions) below for guidance.
-6.  **Incremental contributions: One document at a time, procedures first**
-    - Third-party document PRs should contain at most one new document.
-    - Any given product's first docs contribution should be a **_Quickstart_** or **_How-to_**.
-    - Additional documents will be merged only if we can verify that our readers are deriving value from your initial contribution.
-    - The way that we verify this isn't yet formally established, and it isn't publicly disclosed. Our current approach combines a number of objective and subjective measures.
-7.  **Policy acknowledgment**
-    - Before merging third-party documentation PRs, we ask contributors to acknowledge that they've read, understood, and agree with the following policies:
-      1. **Content ownership**: As the author, you retain ownership of and responsibility for the content you contribute. You're free to use your content in any way you see fit outside of Arbitrum's docs. Remember that when contributing content to our documentation, you must ensure you have the necessary rights to do so, and that the content doesn't infringe on the intellectual property rights of others.
-      2. **License for use**: By contributing your content to our documentation, you grant Offchain Labs a non-exclusive, royalty-free license to use, reproduce, adapt, translate, distribute, and display the content in our documentation. This allows us to integrate your content into our docs and make it available to all users.
-      3. **Right to modify or remove**: Offchain Labs reserves the right to modify or remove third-party content from our documentation at any time. This might be necessary due to a range of reasons, such as content becoming outdated, receiving very low pageviews over an extended period, or misalignment with our guidelines or goals.
-
-### Update request protocol
+### Add a new third-party document
+
+**Third-party docs** are documents that help readers of Arbitrum docs use other products, services, and protocols (like the ones listed in the [Arbitrum portal](https://portal.arbitrum.io/)) with Arbitrum products.
+
+See [Contribute third-party docs](/for-devs/third-party-docs/contribute) for detailed instructions.
+
+### Request an update
 
 If you'd like to request an update or share a suggestion related to an **existing document** without submitting a pull request to implement the improvement yourself, click the `Request an update` button located at the top of each published document. This button will lead you to a prefilled Github issue that you can use to elaborate on your request or suggestion.
 
-## Content conventions
+<br />
 
-Offchain Labs supports [Arbitrum docs](/) and [Prysm docs](https://docs.prylabs.network/docs/getting-started). The following **content conventions** help us maintain consistency across these documentation sets:
+---
 
 ### Document type conventions
 
@@ -231,7 +191,9 @@ Our published docs are generally organized like this in the sidebar:
 
 <br />
 
-## Frequently asked questions
+---
+
+### Frequently asked questions
 
 #### Can I point to my product from core docs? For example - if my product hosts a public RPC endpoint, can I add it to your [RPC endpoints and providers](/node-running/node-providers) page?
 

website/sidebars.js

@@ -356,6 +356,17 @@ const sidebars = {
           type: 'doc',
           id: 'for-devs/contribute',
         },
+        {
+          type: 'category',
+          label: 'Third-party docs',
+          collapsed: false,
+          items: [
+            {
+              type: 'autogenerated',
+              dirName: 'for-devs/third-party-docs',
+            },
+          ],
+        },
       ],
     },
   ],