doc: add "Troubleshooting" & "best practices"
More discussion on the "Rules of thumb" is in #12744
🏡
Help wanted: let's find these "tips" a better home Fixes: #12636 (closed)
[edit]
As I understand the term "rules of thumb" or "best practices", they are guidelines one should have in mind and try to adhere to, but are not necessarily hard requirements. Our requirements should be stated in the other parts of the document.
[/edit]
My suggestion for a few "rules of thumb" for code contributions. These are obviously my personal opinion, so this PR welcomes edit and suggestions. I do think that we should put some loose guidelines in writing.
The following made me think of this, and are not critique! Ref: https://github.com/nodejs/node/pull/12603 - motivation Ref: https://github.com/nodejs/node/pull/12735 - size
Open questions:
- A significant amount of the first-time contributors don't look at this document at all. So is this the best place to put this?
- Are some of these not just rules of thumb but rather requirements that are better moved to appropriate places of the document.
Add a "catch all" document for tips & trick. When adding an item, try to include the original error message or some keyword so that this doc will popup in Search.
Ref: https://github.com/nodejs/node/issues/12786
Checklist
-
documentation is changed or added -
commit message follows commit guidelines
Affected core subsystem(s)
doc
/cc @vsemozhetbyt @gibfahn