Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
avivkeller opened this issue Jun 4, 2025 · 2 comments · May be fixed by #7837
Open

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

avivkeller opened this issue Jun 4, 2025 · 2 comments · May be fixed by #7837
Assignees
Labels
meta Meta Issues for Administration of the Website Team

Comments

@avivkeller
Copy link
Member

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.

@avivkeller avivkeller added the meta Meta Issues for Administration of the Website Team label Jun 4, 2025
@github-project-automation github-project-automation bot moved this to 📋 Backlog in Node.js Website Jun 4, 2025
@avivkeller avivkeller self-assigned this Jun 4, 2025
@avivkeller avivkeller linked a pull request Jun 4, 2025 that will close this issue
@ovflowd
Copy link
Member

ovflowd commented Jun 5, 2025

Strong +1 appreciate you for handling this!

@avivkeller avivkeller moved this from 📋 Backlog to 🏗 In progress in Node.js Website Jun 5, 2025
@AugustinMauroy
Copy link
Member

+1

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
meta Meta Issues for Administration of the Website Team
Projects
Status: 🏗 In progress
Development

Successfully merging a pull request may close this issue.

3 participants