Improvements to guides

Author: josevalim

_data/getting-started.yml

@@ -58,22 +58,21 @@
     - title: try, catch, and rescue
       slug: try-catch-and-rescue
 
-    - title: Typespecs and behaviours
-      slug: typespecs-and-behaviours
-
     - title: Optional syntax sheet
       slug: optional-syntax
 
+    - title: Erlang libraries
+      slug: erlang-libraries
+
     - title: Debugging
       slug: debugging
 
-    - title: Erlang libraries
-      slug: erlang-libraries
+    - title: Typespecs and behaviours
+      slug: typespecs-and-behaviours
 
     - title: Where to go next
       slug: where-to-go-next
 
-
 - title: Mix and OTP
   dir: /getting-started/mix-otp/
   pages:

getting-started/debugging.markdown

@@ -145,22 +145,22 @@ The above will open another Graphical User Interface that provides many panes to
 
 We explore the Observer in the context of an actual project [in the Dynamic Supervisor chapter of the Mix & OTP guide](/getting-started/mix-otp/dynamic-supervisor.html). This is one of the debugging techniques [the Phoenix framework used to achieve 2 million connections on a single machine](https://phoenixframework.org/blog/the-road-to-2-million-websocket-connections).
 
+If you are using the Phoenix web framework, it ships with the [Phoenix LiveDashboard](https://github.com/phoenixframework/phoenix_live_dashboard), a web dashboard for production nodes which provides similar features to Observer.
+
 Finally, remember you can also get a mini-overview of the runtime info by calling `runtime_info/0` directly in IEx.
 
 ## Other tools and community
 
 We have just scratched the surface of what the Erlang VM has to offer, for example:
 
   * Alongside the observer application, Erlang also includes a `:crashdump_viewer` to view crash dumps
+
   * Integration with OS level tracers, such as [Linux Trace Toolkit,](http://www.erlang.org/doc/apps/runtime_tools/LTTng.html) [DTRACE,](http://www.erlang.org/doc/apps/runtime_tools/DTRACE.html) and [SystemTap](http://www.erlang.org/doc/apps/runtime_tools/SYSTEMTAP.html)
+
   * [Microstate accounting](http://www.erlang.org/doc/man/msacc.html) measures how much time the runtime spends in several low-level tasks in a short time interval
-  * Mix ships with many tasks under the `profile` namespace, such as `cprof` and `fprof`
-  * And more
 
-The community has also created its own tools, often to aid in production, other times in development:
+  * Mix ships with many tasks under the `profile` namespace, such as `cprof` and `fprof`
 
-  * [Phoenix LiveDashboard](https://github.com/phoenixframework/phoenix_live_dashboard) a dashboard for production nodes through a web interface.
-  * [visualixir](https://github.com/koudelka/visualixir) is a development-time process message visualizer.
-  * [erlyberly](https://github.com/andytill/erlyberly) is a GUI for tracing during development.
+  * For more advanced use cases, we recommend the excellent [Erlang in Anger](https://www.erlang-in-anger.com/), which is available as a free ebook
 
 Happy debugging!

getting-started/erlang-libraries.markdown

@@ -199,3 +199,5 @@ iex> byte_size compressed
 iex> :zlib.uncompress(compressed)
 "\nMary had a little lamb,\nHis fleece was white as snow,\nAnd everywhere that Mary went,\nThe lamb was sure to go."
 ```
+
+Now let's take a look at existing Elixir (and Erlang) libraries you might use while debugging.

getting-started/keywords-and-maps.markdown

@@ -220,7 +220,7 @@ iex> if true, do: "This will be seen", else: "This won't"
 "This will be seen"
 ```
 
-Pay close attention to both syntaxes. In the keyword list format, we separate each key-value pair with commas, and each key is followed by `:`. In the `do`-blocks, we get rid of the commas and separate each keyword by a newline. They are useful exactly because they remove the verbosity when writing blocks of code. Most of the time, you will use the block syntax, but it is good to know they are equivalent.
+Pay close attention to both syntaxes. In the keyword list format, we separate each key-value pair with commas, and each key is followed by `:`. In the `do`-blocks, we get rid of the colons, the commas, and separate each keyword by a newline. They are useful exactly because they remove the verbosity when writing blocks of code. Most of the time, you will use the block syntax, but it is good to know they are equivalent.
 
 Note that only a handful of keyword lists can be converted to blocks: `do`, `else`, `catch`, `rescue`, and `after`. Those are all the keywords used by Elixir control-flow constructs. We have already learned some of them and we will learn others in the future.
 

getting-started/optional-syntax.markdown

@@ -20,12 +20,15 @@ iex> if true do
 ...> else
 ...>   :that
 ...> end
+:this
 
 # keyword lists
 iex> if true, do: :this, else: :that
 :this
 ```
 
+Keyword lists use Elixir's regular notation for separating arguments, where we separate each key-value pair with commas, and each key is followed by `:`. In the `do`-blocks, we get rid of the colons, the commas, and separate each keyword by a newline. They are useful exactly because they remove the verbosity when writing blocks of code. Most of the time, we use the block syntax, but it is good to know they are equivalent.
+
 Those conveniences, which we call here "optional syntax", allow the language syntax core to be small, without sacrificing the readability and expressiveness of your code.  In this brief chapter, we will review the four rules provided by the language, using a short snippet as playground.
 
 ## Walk-through
@@ -66,7 +69,7 @@ Now let's remove the conveniences one by one:
    if(variable?, [{:do, Call.this()}, {:else, Call.that()}])
    ```
 
-That's it! Those four rules outline the optional syntax of the code we have written so far. Whenever you have any questions, this quick walk-through has you covered.
+That's it! Those four rules outline the optional syntax available in Elixir. Those rules apply everywhere consistently, regardless of the construct you are invoking. Whenever you have any questions, this quick walk-through has you covered.
 
 At the end of the day, those rules are what enables us to write: