Skip to content

Improve README.md for Better Onboarding and Clarity #6120

@holyaustin

Description

@holyaustin

📝 Description

The current README.md in the graph-node repository is functional but lacks a clear structure, modern documentation flow, and beginner-friendly onboarding guidance. This makes it harder for new contributors and subgraph developers to quickly understand how to run and contribute to Graph Node.

🔧 Proposed Improvements

I propose the following enhancements to the README.md:

  • Add a clear title and project description with badges (build status, docs, Discord)
  • Restructure content with intuitive sections:
    • Overview
    • Getting Started (Docker vs. source)
    • Prerequisites
    • Build and Run
    • Deploy a Subgraph
    • Advanced Configuration
    • Contributing
    • License
  • Add Docker setup instructions — recommended for most developers
  • Improve readability with tables, code blocks, and links
  • Guide first-time contributors with a "Good First Issues" link
  • Modernize tone and flow for better onboarding

Why This Matters

  • Thousands of developers use Graph Node — a clearer README reduces friction
  • Better documentation = faster onboarding = more contributions
  • Aligns with best practices in open-source projects

Next Steps

Once this issue is accepted, I will:

  1. Fork the repo
  2. Create a branch
  3. Update the README.md with the proposed structure
  4. Submit a pull request for review

I welcome feedback on the proposed structure before implementation.

Thank you!

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions