Review comments

Author: mhegazy

CONTRIBUTING.md

@@ -2,23 +2,31 @@
 
 ## Contributing fixes to existing samples
 
-A bug must have an issue tracking it in the issue tracker that has been approved (labeled "help wanted") by the TypeScript team.
+A bug must have an issue tracking it in the issue tracker that has been approved (Lable: "help wanted") by the TypeScript team.
 Your pull request should include a link to the bug that you are fixing.
-If you've submitted a PR for a bug, please post a comment on the issue to avoid duplication of effort.
+If you've submitted a PR for a bug, please post a comment in the bug to avoid duplication of effort.
 
 ## Contributing new samples
 
-New samples may be accepted, but will need to first be approved (marked "help wanted" by a TypeScript coordinator with the message "Approved") in the suggestion issue. 
+New samples may be accepted, but will need to first be approved (marked as Label: "help wanted" by a TypeScript coordinator) in the suggestion issue.
 
 For new samples, please provide a detailed explanation of the intended sample, list of technologies or tools used, and an explanation of why existing samples are not sufficient and a new sample is needed.
 
-A new sample should:
+A sample is meant to showcase a specific technology or toolchain integration with TypeScript; a sample is not meant to be a template that users would use to get a project going.
+A sample should only include tools/technologies that serve the main technology it covers; for instance, a sample for a UI framework should not include a test framework integration.
 
-* include a detailed `README.md` file describing how to setup, build, and run the sample.
-* include a `tsconfig.json`.
-* build against a publicly released version of the TypeScript toolset.
-* only include tools/technolgies that serve the main purpose of the sample (e.g. no test frameworks unless showcasing a test framework).
-* work across all platforms.
+A sample should be well documented.
+Please include comments in `readme.md` explaining why steps are being taken, including in build files if applicable.
+A good sample `readme.md` should read like a walkthrough, guiding the reader through different steps of setting up and building the sample.
+See [TypeScript quick start samples](https://github.com/Microsoft/TypeScript-Handbook/tree/master/pages/quick-start) for guidance.
+
+A sample should be self-contained.
+[npm](https://www.npmjs.com/) is the recommended way of acquiring dependencies.
+[typings](https://github.com/typings/typings) is the recommended way of acquiring definition files.
+
+A sample should be IDE/editor-friendly. Please include a `tsconfig.json` file at the root.
+
+A sample should have no OS dependency.
 
 ## Legal
 
@@ -28,5 +36,4 @@ Briefly, this agreement testifies that you are granting us permission to use the
 Please submit a Contributor License Agreement (CLA) before submitting a pull request.
 You may visit https://cla.microsoft.com to sign digitally.
 Alternatively, download the agreement ([Microsoft Contribution License Agreement.docx](https://www.codeplex.com/Download?ProjectName=typescript&DownloadId=822190) or [Microsoft Contribution License Agreement.pdf](https://www.codeplex.com/Download?ProjectName=typescript&DownloadId=921298)), sign, scan, and email it back to <[email protected]>.
-Be sure to include your github user name along with the agreement.
-Once we have received the signed CLA, we'll review the request. 
+Be sure to include your github user name along with the agreement. Once we have received the signed CLA, we'll review the request.