revert: docs: corrections and further clarifications

This reverts commit 7cb5446bb597b2a457ae4390a0658da5779ffb70.

README.md

@@ -93,22 +93,22 @@ After running the tests, the command `semantic-release` will execute the followi
 ## Documentation
 
 - Usage
-  - [Getting started](docs/01-usage/getting-started.md)
+  - [Getting started](docs/01-usage/01-getting-started.md)
   - [Installation](docs/01-usage/installation.md#installation)
   - [CI Configuration](docs/01-usage/ci-configuration.md#ci-configuration)
   - [Configuration](docs/01-usage/configuration.md#configuration)
   - [Plugins](docs/01-usage/plugins.md)
   - [Shareable configurations](docs/01-usage/shareable-configurations.md)
 - Extending
-  - [Available plugins](docs/02-extending/plugins-list.md)
+  - [Plugins](docs/02-extending/plugins-list.md)
-  - [Available shareable configuration](docs/02-extending/shareable-configurations-list.md)
+  - [Shareable configuration](docs/02-extending/shareable-configurations-list.md)
 - Recipes
   - [CI pipelines recipes](docs/03-recipes/ci-pipelines-recipes.md)
-    - [CircleCI 2.0 workflows](docs/03-recipes/circleci-workflows.md)
+	- [CircleCI 2.0 workflows](docs/03-recipes/circleci-workflows.md)
-    - [Travis CI](docs/03-recipes/travis.md)
+	- [Travis CI](docs/03-recipes/travis.md)
-    - [GitLab CI](docs/03-recipes/gitlab-ci.md)
+	- [GitLab CI](docs/03-recipes/gitlab-ci.md)
   - [Git hosted services](docs/03-recipes/git-hosted-services.md)
-    - [Git authentication with SSH keys](docs/03-recipes/git-auth-ssh-keys.md)
+	- [Git authentication with SSH keys](docs/03-recipes/git-auth-ssh-keys.md)
   - [Package managers and languages](docs/03-recipes/package-managers-and-languages.md)
 - Developer guide
   - [JavaScript API](docs/04-developer-guide/js-api.md)

SUMMARY.md

@@ -9,16 +9,16 @@
 - [Shareable configurations](docs/01-usage/shareable-configurations.md)
 
 ## Extensions
-- [Available plugins](docs/02-extending/plugins-list.md)
+- [Plugins](docs/02-extending/plugins-list.md)
-- [Available shareable configuration](docs/02-extending/shareable-configurations-list.md)
+- [Shareable configuration](docs/02-extending/shareable-configurations-list.md)
 
 ## Recipes
 - [CI pipelines recipes](docs/03-recipes/ci-pipelines-recipes.md)
-  - [CircleCI 2.0 workflows](docs/03-recipes/circleci-workflows.md)
+	- [CircleCI 2.0 workflows](docs/03-recipes/circleci-workflows.md)
-  - [Travis CI](docs/03-recipes/travis.md)
+	- [Travis CI](docs/03-recipes/travis.md)
-  - [GitLab CI](docs/03-recipes/gitlab-ci.md)
+	- [GitLab CI](docs/03-recipes/gitlab-ci.md)
 - [Git hosted services](docs/03-recipes/git-hosted-services.md)
-  - [Git authentication with SSH keys](docs/03-recipes/git-auth-ssh-keys.md)
+	- [Git authentication with SSH keys](docs/03-recipes/git-auth-ssh-keys.md)
 - [Package managers and languages](docs/03-recipes/package-managers-and-languages.md)
 
 ## Developer guide

docs/01-usage/configuration.md

@@ -154,7 +154,7 @@ Example (`.releaserc` file content):
     "@semantic-release/release-notes-generator",
     "@semantic-release-docker",
     ["@semantic-release/exec", {
-      "verifyConditionsCmd": "./verify.sh"
+      "verifyConditionsCmd": "./verify.sh"    # plugin configuration
     }],
     "@semantic-release/git",
     "@semantic-release/gitlab",

docs/01-usage/installation.md

@@ -18,5 +18,12 @@ $ npx semantic-release
 
 ## Global installation
 
-> **Note:** Global installation is no longer recommended. Please use local installation and `npx` instead.
+For other type of projects we recommend installing **semantic-release** directly in the CI environment, also with [npx](https://www.npmjs.com/package/npx):
 
+```bash
+$ npx semantic-release
+```
+
+> **Note:** For a global installation, it's recommended to specify the major **semantic-release** version to install (for example with with `npx semantic-release@15`, or `npm install -g semantic-release@15`). This way your build will not automatically use the next major **semantic-release** release that could possibly break your build. You will have to upgrade manually when a new major version is released.
+
+> **Note:** `npx` is a tool bundled with `npm@>=5.2.0`. It is used to conveniently install the semantic-release binary and to execute it. See [What is npx](../05-support/FAQ.md#what-is-npx) for more details.

docs/01-usage/plugins.md

@@ -75,11 +75,11 @@ Global plugin options can defined at the root of the **semantic-release** config
     "@semantic-release/commit-analyzer",
     "@semantic-release/release-notes-generator",
     ["@semantic-release/github", {
-      "assets": ["dist/**"]
+      "assets": ["dist/**"]                # plugin configuration
       }],
     "@semantic-release/git"
   ],
-  "preset": "angular"
+  "preset": "angular"                      # option passed to all plugins
 }
 ```
 

docs/01-usage/shareable-configurations.md

@@ -1,7 +1,7 @@
 # Shareable configurations
 
-A shareable configuration is an npm package that exports a **semantic-release** configuration object. It allows for use of the same configuration across several projects.
+A shareable configuration is an [npm](https://www.npmjs.com/) package that exports a **semantic-release** configuration object. It allows for use of the same configuration across several projects.
 
-Shareable configurations to be use can be declared with the [`extends` option](configuration.md#extends).
+The shareable configurations to use can be set with the [extends](configuration.md#extends) option.
 
-See [shareable configurations list](../02-extending/shareable-configurations-list.md) for examples.
+See [shareable configurations list](../02-extending/shareable-configurations-list.md).

docs/03-recipes/ci-configurations-recipes.md

@@ -1,4 +1,4 @@
-# CI pipelines recipes
+# CI configurations
 - [CircleCI 2.0 workflows](circleci-workflows.md)
 - [Travis CI](travis.md)
 - [GitLab CI](gitlab-ci.md)

docs/03-recipes/git-hosted-services.md

@@ -1,2 +1,12 @@
-# Git hosted services
+# Recipes
+
+## CI configurations
+- [CircleCI 2.0 workflows](circleci-workflows.md)
+- [Travis CI](travis.md)
+- [GitLab CI](gitlab-ci.md)
+
+## Git hosted services
 - [Git authentication with SSH keys](git-auth-ssh-keys.md)
+
+## Package managers and languages (to be completed)
+