Skip to content

doc/markdown file organization lacks coherence #31741

@sam-github

Description

@sam-github

Over time, the docs have spread across many directory levels. I suggest they be moved around a bit to simplify the arrangement for consistency and discoverability.

Current state, edited to remove docs that are clearly in the right place (doc/changelogs, doc/api), with notes:

.
├── BUILDING.md
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── GOVERNANCE.md
├── README.md
└── SECURITY.md
> Above are pretty traditional for project root dirs.
├── COLLABORATOR_GUIDE.md
> Its a guide, move to doc/guides/. CONTRIBUTING is the top-level for people just starting
├── CPP_STYLE_GUIDE.md
> Its a guide, move to doc/guides/.
├── benchmark
│   ├── README.md
│   └── writing-and-running-benchmarks.md
> Its a guide, move to doc/guides/writing-benchmarks, like doc/guides/writing-tests.md
├── doc
│   ├── guides
│   │   ├── adding-new-napi-api.md
│   │   ├── backporting-to-release-lines.md
│   │   ├── building-node-with-ninja.md
│   │   ├── contributing
│   │   │   ├── coc.md
│   │   │   ├── issues.md
│   │   │   └── pull-requests.md
> Perhaps there is a functional reason these three are here? Otherwise, coc.md seems like it should be CODE_OF_CONDUCT.md
│   │   ├── cve_management_process.md
│   │   ├── diagnostic-tooling-support-tiers.md
│   │   ├── internal
│   │   │   └── readme.md
> Not clear why this is here on its lonesome, move to doc/guides/internal-api.md? or doc/api/internal.md?
│   │   ├── maintaining-icu.md
│   │   ├── maintaining-npm.md
│   │   ├── maintaining-the-build-files.md
│   │   ├── maintaining-V8.md
│   │   ├── node-postmortem-support.md
│   │   ├── security_release_process.md
> Move to security-release-process.md
│   │   ├── updating-root-certs.md
> Move to maintaining-root-certs.md
│   │   ├── using-internal-errors.md
│   │   ├── using-symbols.md
│   │   └── writing-tests.md
.doc+
│   ├── offboarding.md
│   ├── onboarding-extras.md
│   ├── onboarding.md
│   ├── releases.md
> Move all 4 above to guides/? releases.md is here, security releases are in guides/, this is odd.
│   └── STYLE_GUIDE.md
> Move to guides/documentation-style.md?

Also: we have randomly use both README.md and readme.md as file names, and should probably just use the uppercase version:

./benchmark/README.md
./README.md
./test/wasi/README.md
./test/fixtures/0-dns/README.md
./test/fixtures/wpt/url/README.md
./test/fixtures/wpt/resources/webidl2/README.md
./test/fixtures/wpt/resources/readme.md
./test/fixtures/wpt/README.md
./test/README.md
./test/wpt/README.md
./test/common/README.md
./doc/guides/internal/readme.md
./lib/internal/readme.md
./src/README.md

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