update documentation

2 files changed, 15 insertions, 10 deletions

diff --git a/Documentation/building.md b/Documentation/building.md
index 50ce328..24d14de 100644
--- a/Documentation/building.md
+++ b/Documentation/building.md
@@ -58,7 +58,7 @@ The native library produced in the previous step may be bundled into a "fat" jar
 Note: an important feature of fat jars is to include native libraries for several platforms. To copy binaries compiled on other platforms to the fat jar, place them in a subfolder of `flow-native-sbt/lib_native`. The subfolder should have the name `$(os.name)-$(os.arch)`, where `os.name` and `os.arch` are the Java system properties of the respective platforms.
 
 ### Note About Versioning
-The project and package versions follow a sematic pattern: `M.m.p`, where
+The project and package versions follow a [sematic](http://semver.org/) pattern: `M.m.p`, where
 
 - `M` is the major version, representing backwards incompatible changes
 
diff --git a/Documentation/getting-started.md b/Documentation/getting-started.md
index c58195b..d681dd6 100644
--- a/Documentation/getting-started.md
+++ b/Documentation/getting-started.md
@@ -1,10 +1,18 @@
 # Getting Started
-Flow uses SBT as build system. To get started, include a dependency to flow-core in your project:
+Flow uses SBT as build system. To get started, include a dependency to flow in your project:
 
-    libraryDependencies += "com.github.jodersky" %% "flow" % "2.2.4"
+	libraryDependencies += "com.github.jodersky" %% "flow" % "2.2.4"
+
+Next, you need to include flow's native library that supports communication for serial devices.
 
 ## Including Native Library
-*NOTICE: flow uses native libraries to back serial communication, therefore before you can run any application depending on flow you must include flow's native library! To do so, you have two options.*
+There are two options to include the native library:
+
+1. Using an easy, pre-packaged dependency, avialble only for certain OSes.
+
+2. Including the library manually for maximum portability.
+
+It is recommended that you use the first option for testing purposes or end-user applications. The second option is recomended for libraries, since it leaves more choice to the end-user.
 
 ### The Easy Way
 In case your OS/architecture combination is present in the table below, add a second dependency to your project:
@@ -20,7 +28,9 @@ This will add a jar to your classpath containing native libraries for various pl
 However, since the JVM does not enable full determination of the current platform (only OS and rough architecture are known), only a couple of platforms can be supported through this solution at the same time.
 
 ### Maximum Portability
-Do not include the second dependency above. Instead, for every end-user application that relies on flow, manually add the native library for the current platform to the JVM's library path. This can be achieved through various ways, notably:
+First, obtain a copy of the native library, either by building flow (see section [Build](./building)) or by downloading a precompiled version from GitHub releases. Native libraries need to be of major version 3 to work with this version of flow.
+
+Second, for every end-user application that relies on flow, manually add the native library for the current platform to the JVM's library path. This can be achieved through various ways, notably:
 
 - Per application:
   Run your program with the command-line option ```-Djava.library.path=".:<folder containing libflow3.so>"```. E.g. ```java -Djava.library.path=".:/home/<folder containing libflow3.so>" -jar your-app.jar```
@@ -30,8 +40,3 @@ Do not include the second dependency above. Instead, for every end-user applicat
 	- Copy the native library to a place that is on the default Java library path and run your application normally. Such places usually include `/usr/lib` and `/usr/local/lib`.
 
 	- Use a provided installer (currently Debian archive and Mac .pkg, available in releases)
-
-The native library can either be obtained by building flow (see section Build) or by taking a pre-compiled one, found in releases in the GitHub project. Native libraries need to be of major version 3 to work with this version of flow.
-
-
-It is recommended that you use the first option only for testing purposes or end-user applications. The second option is recomended for libraries, since it leaves more choice to the end-user.