Skip to content

doc/markdown file organization lacks coherence #31741

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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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