Skip to content

Reorganize documentation structure (CONTRIBUTING.md vs COLLABORATOR_GUIDE.md) #7836

Closed

Description

@avivkeller

As discussed on Slack, the documentation structure should be clear and intuitive, and not in large, hard-to-parse (for newcomers) files.

Our main issues are that:

  1. COLLABORATOR_GUIDE.md contains general contribution information that should be accessible to all contributors, not just collaborators
  2. CONTRIBUTING.md contains actual collaborator guidelines, which feels backwards
  3. COLLABORATOR_GUIDE.md is too large and covers too many topics - it should be broken down into focused files.

With that in mind, following the pattern used by Node.js core (https://github.com/nodejs/node/tree/main/doc/contributing), we should break down our contributing guide into:

docs/
├── README.md (navigation guide)
├── getting-started.md
├── code-style.md
├── writing-tests.md
├── adding-pages.md
└── collaborator-guide.md
...

This will make the documentation more accessible and easier to maintain for both new contributors and collaborators.

Activity

  1. added
    metaMeta Issues for Administration of the Website Team
    on Jun 4, 2025
  2. added theissue type on Jun 4, 2025
  3. self-assigned this
    on Jun 4, 2025
  4. ovflowd commented on Jun 5, 2025

    @ovflowd
    Member

    Strong +1 appreciate you for handling this!

  5. moved this from 📋 Backlog to 🏗 In progress in Node.js Websiteon Jun 5, 2025
  6. AugustinMauroy commented on Jun 5, 2025

    @AugustinMauroy
    Member

    +1

  7. moved this from 🏗 In progress to ✅ Done in Node.js Websiteon Jun 8, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

metaMeta Issues for Administration of the Website Team

Type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions