doc: add styleguide

[bnb]

This PR adds a documentation style guide. This comes as a result of https://github.com/nodejs/node/discussions/40953 and the various next-10 discussions that led to it. It is largely a copy/paste from electron/electron's styleguide.md, with some changes.

The goal of this is not to have it as an immediately enforceable, but rather to have it be planted as the guide that we'll eventually fully enforce on all documentation that it can be enforced on (some documentation, like native APIs, it can only be partially enforced on).

Landing this and, eventually, having all of our documentation written in this style should allows us the ability to use docs-parser which produces a high-quality JSON output of markdown documentation written as the style guide defines. This would allow the DefinitelyTyped people to produce higher quality type definitions, potentially even just using Electron's typescript-definitions tooling that parses docs-parser output into .d.ts files.

There are other, less objective benefits:

• highly consistent authoring experience that provides a consistent framework for writing and reviewing documentation
• more digestible documentation for end-users, structuring all documentation in a hierarchy that's consistent across pages while still being specific enough to provide meaningful context regardless of content

Worth noting, I also created #32206 some time ago, and this is one step towards that as a reality. In doing so, I also created bnb/node-docs-parser which snapshotted a few examples from the Node.js documentation at the time I created it and provided an example of what those documents would look like if they were migrated. While it's been a pandemic worth of time since I last worked on that repo and some of the docs have been updated (querystring in particular is much more consistent!), the documents in /docs/api are still pretty close to what the "translated" versions would look like if you want a reference.

changes to the styleguide.md from the e/e version include:

• updating the name (Electron > Node.js)
• removing references to markdownlint
  • given that Electron and docs-parser use markdownlint, it might make sense to migrate to it.
• removed a TODO above the linter rules, noting that they should be checked against what the electron/electron markdown parser checks for.
  • potentially worth investigating finding a middle ground and both using one set of tooling.
• tweaked examples to fit Node.js. As we build out the documentation to fit this style guide, we should update these examples to me more thorough.
• removed one example under the "function signature" heading on line 169, as I'm not immediately familiar of a class that has the same name as its module and can be used as an example. Happy to re-add this when I find a good example.
  • here's the original text, for reference:

    • For example, the methods of the Session class under the session module must use ses as the objectName.

• removed a reference on line 181 to Electron's cookie API custom sturcutre. Happy to re-add this back in once we've got our own custom structures added.
• added backticks to line 228 where they weren't in the Electron documentation. I believe the backticks are allowed/required, but should double check just to make sure that's a correct assertion before merging.

a few things to discuss:

• js code linting
  • Electron's standardized on StandardJS and has proper tooling for it, including standard-markdown. While I'm personally fine with this, I assume the Node.js project would want a different linter solution documented.
  • happy to change the text on lines 55-56 referencing this if we don't want to keep this.
• I'm not sure if we have platform-specific functionality. If we don't and never plan on doing so, happy to remove line 194-203.
• how we want to approach inline YAML changelogs. Particularly, it was raised that it would be nice to have in Markdown but it may also become burdensome for those who backport, which is definitely not something I'd want to see.
  • potential solution here is to document an additional markdown structure for changelogs and then have a small tool convert YAML into that Markdown structure as a build step.
  • I'm unopinionated on what a solution is here, but ideally, we will eventually not have any YAML frontmatter.

and just for context, the ideal next steps after this PR lands would be to begin incrementally migrating documentation to fit the style guide.

[bnb]

I'll update this tomorrow with a definition on how to fit in the Changelog section in Markdown rather than YAML. Wanted to get this up ASAP, though :)

[bnb]

Improved line lengths, ran make format-md, and tossed in some backticks to examples so the linter doesn't screech at links that don't exist.

[targos]

@nodejs/documentation

[DerekNonGeneric]

@bnb, this PR is confusing to me since I was not part of this discussion — it seems like this is the result of some @nodejs/next-10 discussions that took place recently, but perhaps even more recently was another discussion had by myself, @GeoffreyBooth, and @Trott…

---

We are currently using the Microsoft Docs styleguide — would anyone like to explain why the change? I am not necessarily opposed to a change, but this seems to be contrary to what we have been using so far…

[DerekNonGeneric]

I am +1 to using title case for titles.

I still haven't figured out why we have not been using this from the beginning other than wanting to do what MDN does, which doesn't seem properly justified.

[DerekNonGeneric]

Suggested change

	### Title and description
	### Title and Description

APA title case would need to be applied to all of these titles.

How can we lint for this? I would like to do so.

[Trott]

APA title case would need to be applied to all of these titles.

This is not the title of the page and per the text above, should be sentence case.

[DerekNonGeneric]

You are correct in that this not being the title of the page; however, it is the title of a section of the page. We can call them “chapters” as @bnb proposes.

Other words for this could be “segments”, “sections”, etc…

[GeoffreyBooth]

This feels like a very big change, essentially a rewrite/reformatting of all of Node’s documentation. While making the docs more parseable for type definitions is a worthy goal, I’m not sure that the level of effort required here justifies that payoff.

I’m also a big fan of the policy that we just follow the Microsoft Style Guide and that’s it, and we spare ourselves debates over style questions. Adopting our own styleguide would seem to invite such debates.

Maybe this was already discussed within Next-10 and raised to the TSC, but I think if this is something that the project wants to pursue it should be debated and approved by the TSC. cc @Trott, @nodejs/tsc

[Trott]

We already have a documentation style guide. https://github.com/nodejs/node/blob/e601c0d678f815e00c385c5b5b3b9efd6bcaaf91/doc/guides/doc-style-guide.md

We should not have two duplicative style guides and we should certainly not have two contradictory style guides.

[Trott]

The text says this isn't covered by the linter rules, but it in fact is.

[Trott]

The linter (mostly) enforces 80 character wrapping so this too is enforced by the linter but the text above says it isn't.

[Trott]

I don't believe this is correct.