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: adopt Microsoft Style Guide officially #34821

Closed
wants to merge 0 commits into from
Closed

Conversation

Trott
Copy link
Member

@Trott Trott commented Aug 18, 2020

Checklist
  • make -j4 test (UNIX), or vcbuild test (Windows) passes
  • documentation is changed or added
  • commit message follows commit guidelines

@nodejs-github-bot nodejs-github-bot added the doc Issues and PRs related to the documentations. label Aug 18, 2020
@Trott
Copy link
Member Author

Trott commented Aug 18, 2020

@nodejs/documentation

Copy link
Contributor

@DerekNonGeneric DerekNonGeneric left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You know my preferences on these style guides, but I have no objection.


[Javascript type]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Data_structures_and_types
[Microsoft Writing Style Guide]: https://docs.microsoft.com/en-us/style-guide/welcome/
[`remark-preset-lint-node`]: https://github.com/nodejs/remark-preset-lint-node
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I mentioned this to @addaleax and I don't know of a more appropriate situation to bring it up other than right here, but I wish we could use scoped packages for these: @nodejs/remark-preset-lint-node.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nodejs-core/* maybe, so we differentiate between external packages and packages targeting collaborators?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[…] differentiate between external packages and packages targeting collaborators

Yes, exactly.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mmarchini, sorry, not targeting, but rather collaborating on. Why can't we use @nodejs?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIRC it was originally reserved on npm so we could use it for new modules/standard library to go under this scope (nodejs/TSC#389 for some of the discussions around this). IMO if we end up using it for that purpose, mixing with tooling that is used exclusively on Node.js core will be confusing, so scoping to something specific for the internal workflow of the project makes more sense.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We have plans for another package-scoped bare specifier: @nodejs/resolver-conformance-tests.

Refs: https://github.com/nodejs/modules/issues/472#issuecomment-584994986

@@ -104,10 +104,14 @@ this guide.

See also API documentation structure overview in [doctools README][].

For topics not covered here, refer to the [Microsoft Writing Style Guide][]. For
issues not covered there, refer to _The Chicago Manual of Style_.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add a link to The Chicago Manual of Style?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I"m going to remove the Chicago Manual of Style. It can always be added in a later PR. I'm kind of torn about it. On the one hand, it is pretty much the standard for this sort of stuff. On the other hand, it is not freely available online. Links would be to partial versions, or cheatsheets, or a site where you could buy it.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(And we can always add it later.)

Trott added a commit that referenced this pull request Aug 21, 2020
PR-URL: #34821
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Ricky Zhou <0x19951125@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is>
@Trott
Copy link
Member Author

Trott commented Aug 21, 2020

Landed in bc8a4df

@Trott Trott closed this Aug 21, 2020
@Trott Trott deleted the adopt branch August 21, 2020 13:25
BethGriggs pushed a commit that referenced this pull request Aug 24, 2020
PR-URL: #34821
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Ricky Zhou <0x19951125@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is>
@danielleadams danielleadams mentioned this pull request Aug 25, 2020
addaleax pushed a commit that referenced this pull request Sep 22, 2020
PR-URL: #34821
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Ricky Zhou <0x19951125@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is>
addaleax pushed a commit that referenced this pull request Sep 22, 2020
PR-URL: #34821
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Ricky Zhou <0x19951125@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is>
@codebytere codebytere mentioned this pull request Sep 28, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

8 participants