Skip to content
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

doc/markdown file organization lacks coherence #31741

Closed
sam-github opened this issue Feb 11, 2020 · 4 comments
Closed

doc/markdown file organization lacks coherence #31741

sam-github opened this issue Feb 11, 2020 · 4 comments

Comments

@sam-github
Copy link
Contributor

sam-github commented Feb 11, 2020

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
@richardlau
Copy link
Member

│   └── STYLE_GUIDE.md
> Move to guides/documentation-style.md?

and merge with tools/doc/README.md?

@DavenportEmma
Copy link
Contributor

I'd like to take this issue, if that's ok

@sam-github
Copy link
Contributor Author

Go for it!

DavenportEmma added a commit to DavenportEmma/node that referenced this issue Feb 13, 2020
Merged the CODE_OF_CONDUCT.md and doc/guides/contributing/coc.md
files into a single code of conduct file

Refs: nodejs#31741
DavenportEmma added a commit to DavenportEmma/node that referenced this issue Feb 13, 2020
Changed security_release_process.md to security-release-process.md
to stay consistent with file naming

Refs: nodejs#31741
DavenportEmma added a commit to DavenportEmma/node that referenced this issue Feb 13, 2020
Moved writing-and-running-benchmarks to doc/guides/ directory

Fixes: nodejs#31741
DavenportEmma added a commit to DavenportEmma/node that referenced this issue Feb 13, 2020
Updated updating-root-certs.md to maintaining-root-certs.md

Fixes: nodejs#31741
DavenportEmma added a commit to DavenportEmma/node that referenced this issue Feb 13, 2020
Moved COLLABORATOR_GUIDE, CPP_STYLE_GUIDE, and internal-api to
the appropriate directories

Fixes: nodejs#31741
DavenportEmma added a commit to DavenportEmma/node that referenced this issue Feb 13, 2020
DavenportEmma added a commit to DavenportEmma/node that referenced this issue Feb 13, 2020
Moved STYLE_GUIDE.md to guides/documentation-style.md

Fixes: nodejs#31741
DavenportEmma added a commit to DavenportEmma/node that referenced this issue Feb 14, 2020
Merged the CODE_OF_CONDUCT.md and doc/guides/contributing/coc.md
files into a single code of conduct file

Refs: nodejs#31741
DavenportEmma added a commit to DavenportEmma/node that referenced this issue Feb 14, 2020
Changed security_release_process.md to security-release-process.md
to stay consistent with file naming

Refs: nodejs#31741
DavenportEmma added a commit to DavenportEmma/node that referenced this issue Feb 14, 2020
Moved writing-and-running-benchmarks to doc/guides/ directory

Fixes: nodejs#31741
DavenportEmma added a commit to DavenportEmma/node that referenced this issue Feb 14, 2020
Updated updating-root-certs.md to maintaining-root-certs.md

Fixes: nodejs#31741
DavenportEmma added a commit to DavenportEmma/node that referenced this issue Feb 14, 2020
Moved COLLABORATOR_GUIDE, CPP_STYLE_GUIDE, and internal-api to
the appropriate directories

Fixes: nodejs#31741
DavenportEmma added a commit to DavenportEmma/node that referenced this issue Feb 14, 2020
DavenportEmma added a commit to DavenportEmma/node that referenced this issue Feb 14, 2020
Moved STYLE_GUIDE.md to guides/documentation-style.md

Fixes: nodejs#31741
DavenportEmma added a commit to DavenportEmma/node that referenced this issue Feb 27, 2020
Updated cpp style guide file name and location and fixed links to
this file.

Fixes: nodejs#31741
DavenportEmma added a commit to DavenportEmma/node that referenced this issue Feb 27, 2020
Updated collaborator guide file name and location and fixed links
to this file.

Fixes: nodejs#31741
DavenportEmma added a commit to DavenportEmma/node that referenced this issue Feb 27, 2020
Updated documentation style guide file name and location and updated
links referencing the file.

Fixes: nodejs#31741
DavenportEmma added a commit to DavenportEmma/node that referenced this issue Feb 27, 2020
Fixed the links referencing markdown files that have moved location

Fixes: nodejs#31741
DavenportEmma added a commit to DavenportEmma/node that referenced this issue Feb 27, 2020
Moved files to appropriate location and updated naming style for
some of them.

Fixes: nodejs#31741
MylesBorins pushed a commit that referenced this issue Mar 4, 2020
* Updated cpp style guide file name and location and fixed links to
  this file.

* Updated collaborator guide file name and location and fixed links
  to this file.

* Updated documentation style guide file name and location and updated
  links referencing the file.

* Moved files to appropriate location and updated naming style for
  some of them.

Fixes: #31741

PR-URL: #31792
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
codebytere pushed a commit that referenced this issue Mar 16, 2020
* Updated cpp style guide file name and location and fixed links to
  this file.

* Updated collaborator guide file name and location and fixed links
  to this file.

* Updated documentation style guide file name and location and updated
  links referencing the file.

* Moved files to appropriate location and updated naming style for
  some of them.

Fixes: #31741

PR-URL: #31792
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
codebytere pushed a commit that referenced this issue Mar 17, 2020
* Updated cpp style guide file name and location and fixed links to
  this file.

* Updated collaborator guide file name and location and fixed links
  to this file.

* Updated documentation style guide file name and location and updated
  links referencing the file.

* Moved files to appropriate location and updated naming style for
  some of them.

Fixes: #31741

PR-URL: #31792
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
codebytere pushed a commit that referenced this issue Mar 23, 2020
* Updated cpp style guide file name and location and fixed links to
  this file.

* Updated collaborator guide file name and location and fixed links
  to this file.

* Updated documentation style guide file name and location and updated
  links referencing the file.

* Moved files to appropriate location and updated naming style for
  some of them.

Fixes: #31741

PR-URL: #31792
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
codebytere pushed a commit that referenced this issue Mar 30, 2020
* Updated cpp style guide file name and location and fixed links to
  this file.

* Updated collaborator guide file name and location and fixed links
  to this file.

* Updated documentation style guide file name and location and updated
  links referencing the file.

* Moved files to appropriate location and updated naming style for
  some of them.

Fixes: #31741

PR-URL: #31792
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
5 participants
@sam-github @richardlau @DavenportEmma and others