From 377c70833e519a892f757812cdf97ae96f8d504d Mon Sep 17 00:00:00 2001 From: Yoni Goldberg Date: Thu, 14 Dec 2017 23:17:08 +0200 Subject: [PATCH 1/9] Create writing-guidelines.md --- writing-guidelines.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 writing-guidelines.md diff --git a/writing-guidelines.md b/writing-guidelines.md new file mode 100644 index 00000000..5cbf381a --- /dev/null +++ b/writing-guidelines.md @@ -0,0 +1,22 @@ +# Writing guidelines + +

+ +## it's all about content curation + +summarize and prove that it's true + +

+ + +## Core principles +1. True beyond reasonable doubt - +2. Nicely served - +3. other thing +

+ +## Guidelines +1. First ordered list item +2. Another item +

+ From 656b87543eead965e20f7c629038bea8876cbba4 Mon Sep 17 00:00:00 2001 From: Leonardo Villela Date: Fri, 26 Jan 2018 14:10:06 -0200 Subject: [PATCH 2/9] Update wraputilities.md - Change term "framework" to "tool", because is more correct. --- sections/projectstructre/wraputilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sections/projectstructre/wraputilities.md b/sections/projectstructre/wraputilities.md index 6d47e605..742cc617 100644 --- a/sections/projectstructre/wraputilities.md +++ b/sections/projectstructre/wraputilities.md @@ -4,7 +4,7 @@ ### One Paragraph Explainer -Once you start growing and have different components on different servers which consumes similar utilities, you should start managing the dependencies - how can you keep 1 copy of your utility code and let multiple consumer components use and deploy it? well, there is a framework for that, it's called NPM... Start by wrapping 3rd party utility packages with your own code to make it easily replaceable in the future and publish your own code as private NPM package. Now, all your code base can import that code and benefit free dependency management framework. It's possible to publish NPM packages for your own private use without sharing it publicly using [private modules](https://docs.npmjs.com/private-modules/intro), [private registry](https://npme.npmjs.com/docs/tutorials/npm-enterprise-with-nexus.html) or [local NPM packages](https://medium.com/@arnaudrinquin/build-modular-application-with-npm-local-modules-dfc5ff047bcc) +Once you start growing and have different components on different servers which consumes similar utilities, you should start managing the dependencies - how can you keep 1 copy of your utility code and let multiple consumer components use and deploy it? well, there is a tool for that, it's called NPM... Start by wrapping 3rd party utility packages with your own code to make it easily replaceable in the future and publish your own code as private NPM package. Now, all your code base can import that code and benefit free dependency management tool. It's possible to publish NPM packages for your own private use without sharing it publicly using [private modules](https://docs.npmjs.com/private-modules/intro), [private registry](https://npme.npmjs.com/docs/tutorials/npm-enterprise-with-nexus.html) or [local NPM packages](https://medium.com/@arnaudrinquin/build-modular-application-with-npm-local-modules-dfc5ff047bcc)

From 8fc02e53e1838a716f05de8e52a2b4a6b2f2453e Mon Sep 17 00:00:00 2001 From: Leonardo Villela Date: Fri, 26 Jan 2018 14:13:39 -0200 Subject: [PATCH 3/9] Adding my name to "Thank you" section in README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3e7db9f3..3a844929 100644 --- a/README.md +++ b/README.md @@ -720,7 +720,7 @@ This repository is being kept up to date thanks to the help from the community. 🌻 [Aaron Arney](https://github.com/ocularrhythm), 🌻 [Jan Charles Maghirang Adona](https://github.com/septa97), 🌻 [Allen Fang](https://github.com/AllenFang) - +🌻 [Leonardo Villela](https://github.com/leonardovillela) From 6111c347a940ff230f1dc6056975a01801676d85 Mon Sep 17 00:00:00 2001 From: Bruno Scheufler <4772980+BrunoScheufler@users.noreply.github.com> Date: Fri, 26 Jan 2018 17:17:44 +0100 Subject: [PATCH 4/9] Fixed 'Thank You Notes' Section layout --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3a844929..e69bcda3 100644 --- a/README.md +++ b/README.md @@ -719,7 +719,7 @@ This repository is being kept up to date thanks to the help from the community. 🌻 [Xavier Ho](https://github.com/spaxe), 🌻 [Aaron Arney](https://github.com/ocularrhythm), 🌻 [Jan Charles Maghirang Adona](https://github.com/septa97), -🌻 [Allen Fang](https://github.com/AllenFang) +🌻 [Allen Fang](https://github.com/AllenFang), 🌻 [Leonardo Villela](https://github.com/leonardovillela) From 3e475b0a0d9e59d9405412d14a2ee17e3f573278 Mon Sep 17 00:00:00 2001 From: Yoni Goldberg Date: Mon, 29 Jan 2018 19:47:53 +0100 Subject: [PATCH 5/9] Update writing-guidelines.md --- writing-guidelines.md | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/writing-guidelines.md b/writing-guidelines.md index 5cbf381a..4df9f886 100644 --- a/writing-guidelines.md +++ b/writing-guidelines.md @@ -1,22 +1,25 @@ -# Writing guidelines +# 7 content writing guidelineso -

+##1. Simple is better than better -## it's all about content curation +
+making it easy to read and agree is our mission, we curate content. As such we focus on transforming complex and exhausting topics into a simplified list, we may trade overloaded information with shortened and less-accurate details, avoid ‘flammable’ and controversial topics and escape subjective ideas -summarize and prove that it's true +
-

+##2. Evidence based + +
+Our reader should almost have no doubt while he skims through our content, mostly because we include evidence, references and data. Practically, strive to include quotes from reliable sources, show benchmarks, related design patterns or any scientific measure to prove your claims -## Core principles -1. True beyond reasonable doubt - -2. Nicely served - -3. other thing -

+o MECE – each topic should be Mutually Exclusive and Collaboratively Exhausting. So not only the content is greatly edited and reliable, skimming through it also provides full coverage of the topic. No important sub-topic is left outside. +o Consistent formatting – the content is presented using has a fixed template. Any future content must conform to the same template. If you wish to add new bullets copy a bullet format from an existing bullet. For the ‘additional info’ please use this template -## Guidelines -1. First ordered list item -2. Another item -

+o About Node.JS – each advice should be related directly to Node.JS and not to software development in general. When we advise to implement generic pattern/rule in Node.JS, the content should focus on the Node implementation. For example, when we advise to sanitize all requests input for security reasons, Node-lingo should be used. For example: ‘Use Middlewares to sanitize requests input’ +o Top vendors only – it’s sometime useful to include names of vendors that can address certain challenges like NPM packages, open source tools or even commercial products. To avoid overwhelming with long lists or recommending non-reputable and stable projects, we came up with the following rules: + + Only the top 3 vendors can be recommended –a vendor that appears on the top 3 results in a search engine (Google or GitHub sorted by popularity) for a given relevant keyword can be included in our recommendation. + If it’s a NPM packages it must also be downloaded at least 750/days on average + If it’s an open-source project, it must have been updated at least once in the last 6 months From 34bf1b16e74476da1011f7f7857602a82db66429 Mon Sep 17 00:00:00 2001 From: Yoni Goldberg Date: Mon, 29 Jan 2018 19:48:31 +0100 Subject: [PATCH 6/9] Update writing-guidelines.md --- writing-guidelines.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/writing-guidelines.md b/writing-guidelines.md index 4df9f886..8dc7f012 100644 --- a/writing-guidelines.md +++ b/writing-guidelines.md @@ -1,13 +1,13 @@ -# 7 content writing guidelineso +# 7 content writing guidelines -##1. Simple is better than better +## 1. Simple is better than better
making it easy to read and agree is our mission, we curate content. As such we focus on transforming complex and exhausting topics into a simplified list, we may trade overloaded information with shortened and less-accurate details, avoid ‘flammable’ and controversial topics and escape subjective ideas
-##2. Evidence based +## 2. Evidence based
Our reader should almost have no doubt while he skims through our content, mostly because we include evidence, references and data. Practically, strive to include quotes from reliable sources, show benchmarks, related design patterns or any scientific measure to prove your claims From 9e399e9b9ced8d81a4c63625bd72227a52169e6e Mon Sep 17 00:00:00 2001 From: Yoni Goldberg Date: Mon, 29 Jan 2018 22:50:37 +0100 Subject: [PATCH 7/9] Update writing-guidelines.md --- writing-guidelines.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/writing-guidelines.md b/writing-guidelines.md index 8dc7f012..f8d672ed 100644 --- a/writing-guidelines.md +++ b/writing-guidelines.md @@ -1,25 +1,31 @@ -# 7 content writing guidelines +# Our content writing manifest +How we boost the learning experience of our readers ## 1. Simple is better than better
-making it easy to read and agree is our mission, we curate content. As such we focus on transforming complex and exhausting topics into a simplified list, we may trade overloaded information with shortened and less-accurate details, avoid ‘flammable’ and controversial topics and escape subjective ideas +making it easy to read and absorb is our mission, we curate content. As such we focus on transforming complex and exhausting topics into a simplified list, trade overloaded information with shortened and less-accurate details, avoid ‘flammable’ and controversial topics and escape subjective ideas
## 2. Evidence based
-Our reader should almost have no doubt while he skims through our content, mostly because we include evidence, references and data. Practically, strive to include quotes from reliable sources, show benchmarks, related design patterns or any scientific measure to prove your claims +Our reader should feel great condifence that the content they skims through is reliable. We achieve this by including evidence, references and data. Practically, strive to include quotes from reliable sources, show benchmarks, related design patterns or any scientific measure to prove your claims -o MECE – each topic should be Mutually Exclusive and Collaboratively Exhausting. So not only the content is greatly edited and reliable, skimming through it also provides full coverage of the topic. No important sub-topic is left outside. -o Consistent formatting – the content is presented using has a fixed template. Any future content must conform to the same template. If you wish to add new bullets copy a bullet format from an existing bullet. For the ‘additional info’ please use this template +## 3. MECE (Mutually Exclusive and Collaboratively Exhausting) +Not only the content is greatly edited and reliable, skimming through it also provides full coverage of the topic. No important sub-topic is left outside -o About Node.JS – each advice should be related directly to Node.JS and not to software development in general. When we advise to implement generic pattern/rule in Node.JS, the content should focus on the Node implementation. For example, when we advise to sanitize all requests input for security reasons, Node-lingo should be used. For example: ‘Use Middlewares to sanitize requests input’ +## 4. Consistent formatting +The content is presented using fixed templates. Any future content must conform to the same template. If you wish to add new bullets copy a bullet format from an existing bullet. For the ‘additional info’ please use [this template] (https://github.com/i0natan/nodebestpractices/blob/master/sections/template.md) -o Top vendors only – it’s sometime useful to include names of vendors that can address certain challenges like NPM packages, open source tools or even commercial products. To avoid overwhelming with long lists or recommending non-reputable and stable projects, we came up with the following rules: +## 5. It's About Node.JS +Each advice should be related directly to Node.JS and not to software development in general. When we advise to implement generic pattern/rule in Node.JS, the content should focus on the Node implementation. For example, when we advise to sanitize all requests input for security reasons, Node-lingo should be used - ‘Use Middlewares to sanitize requests input’ - Only the top 3 vendors can be recommended –a vendor that appears on the top 3 results in a search engine (Google or GitHub sorted by popularity) for a given relevant keyword can be included in our recommendation. +## 6. Leading vendors only +It’s sometime useful to include names of vendors that can address certain challenges like NPM packages, open source tools or even commercial products. To avoid overwhelming with long lists or recommending non-reputable and stable projects, we came up with the following rules: + + Only the top 3 vendors can be recommended – a vendor that appears on the top 3 results in a search engine (Google or GitHub sorted by popularity) for a given relevant keyword can be included in our recommendation.  If it’s a NPM packages it must also be downloaded at least 750/days on average  If it’s an open-source project, it must have been updated at least once in the last 6 months From 1ca3531a8afd1b449aa17d9199db37c244b9dce3 Mon Sep 17 00:00:00 2001 From: Bruno Scheufler <4772980+BrunoScheufler@users.noreply.github.com> Date: Tue, 30 Jan 2018 17:06:52 +0100 Subject: [PATCH 8/9] Finalized writing guidelines --- writing-guidelines.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/writing-guidelines.md b/writing-guidelines.md index f8d672ed..1f44c500 100644 --- a/writing-guidelines.md +++ b/writing-guidelines.md @@ -1,31 +1,31 @@ # Our content writing manifest -How we boost the learning experience of our readers +How we enhance the reading and learning experience for our visitors -## 1. Simple is better than better +## 1. Simplicity wins
-making it easy to read and absorb is our mission, we curate content. As such we focus on transforming complex and exhausting topics into a simplified list, trade overloaded information with shortened and less-accurate details, avoid ‘flammable’ and controversial topics and escape subjective ideas +Making it easy to read and absorb knowledge is our mission, we curate content. As such we focus on transforming complex and exhausting topics into a simplified list, trade overloaded information with shortened and less-accurate details, avoid ‘flammable’ and controversial topics and escape subjective ideas in favor of generally accepted practices
-## 2. Evidence based +## 2. Be evidence-based and reliable
-Our reader should feel great condifence that the content they skims through is reliable. We achieve this by including evidence, references and data. Practically, strive to include quotes from reliable sources, show benchmarks, related design patterns or any scientific measure to prove your claims +Our readers should have great confidence that the content they skim through is reliable. We achieve this by including evidence like references, data and other resources available to this topic. Practically, strive to include quotes from reliable sources, show benchmarks, related design patterns or any scientific measure to prove your claims -## 3. MECE (Mutually Exclusive and Collaboratively Exhausting) -Not only the content is greatly edited and reliable, skimming through it also provides full coverage of the topic. No important sub-topic is left outside +## 3. MECE (Mutually Exclusive and Collectively Exhaustive) +Apart from the content being greatly edited and reliable, skimming through it should also provide full coverage of the topic. No important sub-topic should be left out ## 4. Consistent formatting -The content is presented using fixed templates. Any future content must conform to the same template. If you wish to add new bullets copy a bullet format from an existing bullet. For the ‘additional info’ please use [this template] (https://github.com/i0natan/nodebestpractices/blob/master/sections/template.md) +The content is presented using fixed templates. Any future content must conform to the same template. If you wish to add new bullets copy a bullet format from an existing bullet and extend it to your needs. For additional information please view [this template](https://github.com/i0natan/nodebestpractices/blob/master/sections/template.md) ## 5. It's About Node.JS -Each advice should be related directly to Node.JS and not to software development in general. When we advise to implement generic pattern/rule in Node.JS, the content should focus on the Node implementation. For example, when we advise to sanitize all requests input for security reasons, Node-lingo should be used - ‘Use Middlewares to sanitize requests input’ +Each advice should be related directly to Node.JS and not to software development in general. When we advise to implement generic pattern/rule in Node.JS, the content should focus on the Node implementation. For example, when we advise to sanitize all requests input for security reasons, Node-lingo should be used - ‘Use middleware to sanitize request input’ ## 6. Leading vendors only -It’s sometime useful to include names of vendors that can address certain challenges like NPM packages, open source tools or even commercial products. To avoid overwhelming with long lists or recommending non-reputable and stable projects, we came up with the following rules: +Sometimes it's useful to include names of vendors that can address certain challenges and problems like NPM packages, open source tools or even commercial products. To avoid overwhelmingly long lists or recommending non-reputable and unstable projects, we came up with the following rules: - Only the top 3 vendors can be recommended – a vendor that appears on the top 3 results in a search engine (Google or GitHub sorted by popularity) for a given relevant keyword can be included in our recommendation. - If it’s a NPM packages it must also be downloaded at least 750/days on average - If it’s an open-source project, it must have been updated at least once in the last 6 months +- Only the top 3 vendors should be recommended – a vendor that appears in the top 3 results of a search engine (Google or GitHub sorted by popularity) for a given relevant keyword can be included in our recommendation +- If it’s a NPM package it must also be downloaded at least 750 times a day on average +- If it’s an open-source project, it must have been updated at least once in the last 6 months From 79149a2938f824866f02a2d3d40af71c1b4274ec Mon Sep 17 00:00:00 2001 From: Yoni Goldberg Date: Wed, 7 Feb 2018 10:14:24 +0200 Subject: [PATCH 9/9] Update writing-guidelines.md --- writing-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/writing-guidelines.md b/writing-guidelines.md index 1f44c500..2cf1f629 100644 --- a/writing-guidelines.md +++ b/writing-guidelines.md @@ -1,7 +1,7 @@ # Our content writing manifest How we enhance the reading and learning experience for our visitors -## 1. Simplicity wins +## 1. Simple is better than better
Making it easy to read and absorb knowledge is our mission, we curate content. As such we focus on transforming complex and exhausting topics into a simplified list, trade overloaded information with shortened and less-accurate details, avoid ‘flammable’ and controversial topics and escape subjective ideas in favor of generally accepted practices