Clarify effect of .skip() (#3947)

The fact that code inside of a skipped suite is executed, is potentially
counter-intuitive.  By using alternative phrasing, we make it clear how
mocha handles code in skipped suites.

Closes #3932

Author: oliversalzburg

docs/index.md

@@ -566,32 +566,36 @@ _Note_: Hooks, if present, will still be executed.
 
 ## Inclusive Tests
 
-This feature is the inverse of `.only()`. By appending `.skip()`, you may tell Mocha to simply ignore these suite(s) and test case(s). Anything skipped will be marked as [pending](#pending-tests), and reported as such. Here's an example of skipping an entire suite:
+This feature is the inverse of `.only()`. By appending `.skip()`, you may tell Mocha to simply ignore test case(s). Anything skipped will be marked as [pending](#pending-tests), and reported as such. Here's an example of skipping an individual test:
 
 ```js
 describe('Array', function() {
-  describe.skip('#indexOf()', function() {
-    // ...
+  describe('#indexOf()', function() {
+    it.skip('should return -1 unless present', function() {
+      // this test will not be run
+    });
+
+    it('should return the index when present', function() {
+      // this test will be run
+    });
   });
 });
 ```
 
-Or a specific test-case:
+You can also put `.skip()` on an entire suite. This is equivalent to appending `.skip()` onto all tests in the suite. Hooks in the suite are also skipped.
 
 ```js
 describe('Array', function() {
-  describe('#indexOf()', function() {
-    it.skip('should return -1 unless present', function() {
+  describe.skip('#indexOf()', function() {
+    it('should return -1 unless present', function() {
       // this test will not be run
     });
-
-    it('should return the index when present', function() {
-      // this test will be run
-    });
   });
 });
 ```
 
+_Note_: Code in skipped suites, that is placed outside of hooks or tests is still executed, as mocha will still invoke the suite function to build up the suite structure for visualization.
+
 > _Best practice_: Use `.skip()` instead of commenting tests out.
 
 You may also skip _at runtime_ using `this.skip()`. If a test needs an environment or configuration which cannot be detected beforehand, a runtime skip is appropriate. For example: