doc(readme): Fix learning documentation

antquinonez · tmcw · commit 87bfe7e8b7ad · 2016-12-23T12:04:01.000-05:00
diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md
@@ -1,20 +1,15 @@
 # Getting Started
 
-Assuming that you've installed the `documentation` application (`npm install -g documentation` if you haven't), how do you
-get started actually using it to document your code?
+`documentation` is a **documentation generator**. It's used to generates documentation from
+comments _within your code_. `documentation` processes JavaScript comments
+in the JSDoc format. 
 
-Traditionally you might write documentation by creating a new Markdown
-file and typing in each function name and argument. Or you might not
-write documentation at all.
+**But don't worry! Even though it's embedded in your code, JSDoc is not code. It's a simple and standard
+syntax for writing documentation. You don't need to be a developer to use it.**
 
-`documentation` is a **documentation generator**, which means that it expects
-you to document your code _within the code_: special JavaScript comments
-in a format called JSDoc define what ends up in the docs.
+Before you continue, make sure `documentation` is on your system (do `npm install -g documentation`, if not installed).
 
-**But don't worry! Even though it's next to code, JSDoc is a simple and standard
-syntax that you can learn even if you aren't a full-time JavaScript developer.**
-
-Let's dive in.
+Now, let's dive in.
 
 ## The Essentials
 
@@ -34,8 +29,9 @@ function addOne(input) {
 ```
 
 The comment before the `addOne` function is a JSDoc comment. Note that it
-begins with `/**` instead of `/*`. JSDoc requires this: if you were
-to write a comment like
+begins with `/**` instead of `/*`. JSDoc requires this.
+
+If you were to write a comment like
 
 ```js
 // --- INVALID - this is ignored by JSDOC ---
@@ -44,76 +40,89 @@ to write a comment like
 // @returns {number} that number, plus one.
 ```
 
-It would be ignored by JSDoc because it uses `//` syntax instead of `/**`.
+the comment would be ignored by `documentation` because it uses `//` syntax instead of `/**`.
+It's not valid JSDoc syntax.
 
-Okay: so let's break down that example into lines:
+Let's break down the earlier JSDoc example:
 
 ```js
 /**
  * This function adds one to its input.
  * ...
 ```
 
-The first line of the comment is typically the _description_. This part
-says _what the thing is or does_, within the space of a few sentences.
+The first line of the comment is typically the _description_. This section
+says _what the code is or does_.
 
 ```js
  * @param {number} input any number
 ```
 
-The second line is a little more complex. The parts are
+On the second line:
 
-* `@param` is **a tag**: there are many tags, and
-  they all begin with the `@` symbol.
-* `{number}` is **a type**. It says that the input to this function needs
-  to be a JavaScript "number" type. It could also say string, like `{string}`,
+* `@param` is **a tag**: This tag indicates that we'll be documenting a function's parameter.
+* `{number}` is **a type**. It says that the input to this function is
+  a JavaScript "number". It could also say `{string}`,
   `{Object}`, `{Date}`, or any other JavaScript built-in type. And if you
   defined a custom class, like `FooClass`, you can use it as a type too by
   saying `{FooClass}`.
 * `input` is the name of the input variable. It matches what the code
   says right below it (`function addOne(input)`).
 * `any number` is the description of the input.
 
-And then you see the next line: it's very similar to `@param`, but just a little
-different: `@returns` instead of `@param`, and since returned values in JavaScript
-don't have names, it just says the description of the value.
+On the third line, there's `@returns`. JavaScript returned values 
+don't have names, so we just have a description of the value.
 
 ## Optional Parameters
 
-Sometimes libraries allow you to omit a parameter. Documentation should
-make this clear, and luckily there's a syntax that describes it:
+Sometimes functions allow you to omit a parameter. 
+This is the syntax that describes an optional parameter:
 
 ```js
  * @param {number} [input=5] any number
 ```
 
-This means that the number can be omitted, and if it is, it'll default
-to 5.
+If an input is omitted, the default value of 5 will be passed to the function.
+
+## What `documentation` does, so you don't have to
+
+`documentation` does some minor magic to auto-generate documentation. Unless
+you want to read the code for yourself, here's a summary of its magic:
+
+**Inference**: JSDoc lets you specify absolutely everything about your code:
+use @name to say what something is called, @kind for whether it's a function
+or a class, @param for its parameters, and so on. But writing all of that
+explicitly is tedious, so where it can, `documentation` automatically
+populates @name, @kind, and @memberof tags based on its reading of the
+code.
+
+**Normalization**: JSDoc has multiple words for the same thing: you can
+say @augments or @extends and they'll do the same thing.
 
 ## Development Process
 
-If you're actively contributing documentation to a big project, there
+If you're contributing documentation to a large project, there
 are tools to help: [eslint's valid-jsdoc](http://eslint.org/docs/rules/valid-jsdoc) rule
-lets you confirm JSDoc comment presence & validity as part of an
+lets you confirm the presence of, and validate, JSDoc comments as part of an
 automated style check.
 
 ## The Tags
 
-[usejsdoc.com](http://usejsdoc.org/index.html) covers all possible tags in the
-JSDoc syntax, and is a great reference material. The most common tags
-you'll see are:
+[usejsdoc.com](http://usejsdoc.org/index.html) covers all available tags in the
+JSDoc syntax, and is a great reference. The most commonly used tags
+are:
 
-* @param - input values given to a function as an argument
+* @param - input given to a function as an argument
 * @returns - output value of a function
 * @name - explicitly set the documented name of a function, class, or variable
-* @private - along with @public and @protected, you can use @private to document
-  something for yourself without including it in generated documentation,
-  since it isn't part of the public API
-* @example - you can use the @example tag to add code examples of how to
-  use some thing inline with the thing itself
+* @private - you can use @private to document
+  code and not have it included in the generated documentation,
+  maybe it's not part of the public API. There's also @public and @protected 
+* @example - you can use the @example tag to add inline code examples with your
+  documentation
 
-It'll help to remember the available tags if your text editor highlights correct tags: if it
-doesn't, try [using a plugin for JSDoc](https://github.com/documentationjs/documentation/wiki/Text-editor-plugins).
+If your text editor does not highlight JSDoc tags, 
+try [using a plugin for JSDoc](https://github.com/documentationjs/documentation/wiki/Text-editor-plugins).
 
 ## Flow type annotations
 
@@ -127,20 +136,3 @@ function addOne(input: number): number {
   return input + 1;
 }
 ```
-
-## What `documentation` does
-
-Documentation does some minor magic to generate documentation. Unless
-you want to read the code for yourself, here's a summary of how it connects
-to your task as a developer.
-
-**Inference**: JSDoc lets you specify absolutely everything about your code:
-use @name to say what something is called, @kind for whether it's a function
-or a class, @param for its parameters, and so on. But writing all of that
-explicitly is tedious, so where it can, `documentation` can automatically
-fill in @name, @kind, and @memberof tags based on its reading of the source
-code.
-
-**Normalization**: JSDoc has multiple words for the same thing: you can
-say @augments or @extends and they'll do the same thing. `documentation`
-normalizes these values to make them styleable.
