Skip to content

Ambiguity between /node-running and /run-arbitrum-node (unclear entry point for node operators) #3246

Description

@Cripto5588

Problem Description

There is significant overlap and lack of clear hierarchy between docs/node-running/ and docs/run-arbitrum-node/ directories.

Objective evidence: In README.md (commit c735bfa), the "Documentation Content" section lists both:

  • node-running/ → "Node operation guides"
  • run-arbitrum-node/ → "Node setup and configuration"

On the live site (developer.arbitrum.io), the sidebar (sidebars.js) includes both, forcing users to switch between sections without a logical flow.

Impact

  • High cognitive load for new node operators (they don't know whether to start with "setup" or "guide")
  • Fragmented information: Configuration items like environment variables may appear in both directories
  • Maintenance problem: Commit history shows content changes in both directories, meaning the same information can become out of sync

Priority

Medium-High – Affects every new user who comes to the repository to run a node.

Possible Solutions (ordered by effort)

Option A (lowest effort, recommended): Rename node-running/ to node-operations/ and turn run-arbitrum-node/ into node-operations/setup/. Update sidebars.js and vercel.json with redirects.

Option B (medium effort): Consolidate everything into run-arbitrum-node/ and move content from node-running/ as a sub-section called "Operation Guides". Remove the old directory.

Option C (higher effort): Create /node/ as a parent directory with /node/setup/ and /node/operation/. Requires updating more links.

Quick Fix (temporary, while a permanent solution is not yet implemented)

Add a note in README.md right above the directory list:

Note: The node-running/ and run-arbitrum-node/ directories are being consolidated. To set up a node, start with run-arbitrum-node/. For operation guides, use node-running/.

For the maintainer

Open to suggestions on which solution you prefer. I can help with the PR.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions