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.
Problem Description
There is significant overlap and lack of clear hierarchy between
docs/node-running/anddocs/run-arbitrum-node/directories.Objective evidence: In
README.md(commitc735bfa), 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
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/tonode-operations/and turnrun-arbitrum-node/intonode-operations/setup/. Updatesidebars.jsandvercel.jsonwith redirects.Option B (medium effort): Consolidate everything into
run-arbitrum-node/and move content fromnode-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.mdright above the directory list:For the maintainer
Open to suggestions on which solution you prefer. I can help with the PR.