diff --git a/source/index.html.md b/source/index.html.md
index 6ccaa2d..1c2ae00 100644
--- a/source/index.html.md
+++ b/source/index.html.md
@@ -10,14 +10,20 @@ robotic systems for wide variety of applications in research and industry. It
contains a rich collection of ready to use drivers and modules for use in your
own system, and can easily be extended by adding new components.
-This website focusses on building robot systems based on Rock and Syskit,
-Rock's system management layer. It will not cover issues related to Rock's Ruby
-and C++ execution APIs, or only in cases where these plug Syskit limitations.
+This documentation's focus is on building robot systems based on Rock and
+Syskit, Rock's system management layer. It will not cover issues related to
+Rock's lower-level Ruby and C++ execution APIs, or only in cases where these
+plug Syskit limitations.
The most important aspect of this documentation is to explain both the _how_
and the _why_, i.e. describe the parts of Syskit that are relevant to manage a
robot system, but also to explain the underlying design principles that allow
-you to build a _manageable_ system.
+you to build a _manageable_ system. The documentation does not assume any prior
+knowledge about Rock, but does assume that you have more than basic knowledge
+on general software development practices. The tools being implemented in Ruby
+and C++, it's best to know about these languages. However, documentation on
+the basics and principles of a Rock-Syskit system can be followed with basic
+programming knowledge.
A Rock newcomer should read this documentation sequentially. Tutorials and
examples are mixed with more detailed descriptions, with an aim at being progressive.
diff --git a/source/syskit_basics/index.html.md.erb b/source/syskit_basics/index.html.md.erb
index 590b88c..f8c2248 100644
--- a/source/syskit_basics/index.html.md.erb
+++ b/source/syskit_basics/index.html.md.erb
@@ -23,14 +23,24 @@ current terminal.
When applicable, we will breach advanced topics, or explanations about how
things are implemented under-the-hood. These will be clearly indicated by
-a box, just like this one.
-{: .advanced-topic}
+a box like this:
+
+
+
-We'll be following this flow (click on the steps title to go directly there):
+
+ Advanced
+This will hold the summary. Just click on "Advanced".
+
+
+The details will be here.
+
+
-<%= load_svg "syskit_basics/media/flow.svg" %>
-## Basic Concepts
+{: .advanced-topic}
+
+## Basic Concepts {#concepts}
**Design and runtime** Rock is a model-based architecture. A Rock system is
described **at design time**, that is before any piece of the actual
@@ -76,4 +86,39 @@ one component = one package. Libraries should be "fat", components "slim" (i.e.
most of the functionality should be implemented as a component-independent
library.
+## The Flow
+
+The rest of the basics section will be following this flow:
+
+
Bootstrapping a Syskit app with Gazebo and a SDF scene, running Gazebo and visualizing the scene
+
+
+
<%= link_to "Creating an arm control network", "composition.html" %>
+
Compositions
+
+
+
<%= link_to "Holding position in the cartesian space", "constant_generator.html" %>
+
Constant Generator, Profiles
+
+
+
<%= link_to "Binding the component networks to the simulator", "devices.html" %>
+
Devices
+
+
+
<%= link_to "Running the networks", "deployment.html" %>
+
Deployment and runtime
+
+
+
+
That's all for now … [let's get started with our Syskit/Gazebo system](getting_started.html){:.btn .btn-primary}
diff --git a/source/syskit_basics/media/flow.svg b/source/syskit_basics/media/flow.svg
deleted file mode 100644
index b339fcf..0000000
--- a/source/syskit_basics/media/flow.svg
+++ /dev/null
@@ -1,271 +0,0 @@
-
-
-
-
diff --git a/source/workspace/index.html.md.erb b/source/workspace/index.html.md.erb
index 1bff32c..f6b9c47 100644
--- a/source/workspace/index.html.md.erb
+++ b/source/workspace/index.html.md.erb
@@ -8,6 +8,19 @@ directory_sort_info: 0
# Managing a Rock installation
+
+As of today (June 2017), not all the software used in this guide has reached
+Rock mainline repositories. For this reason, one needs to start using the
+buildconf repository on GitHub's
+[`rock-gazebo/buildconf`](https://github.com/rock-gazebo/buildconf) instead of
+the default one at
+[`rock-core/buildconf`](https://github.com/rock-core/buildconf). This
+installation guide already reflects this. This configuration automatically
+selects the 'master' flavor as described in this section
+
+
+## Rock Versions and Flavors
+
A system can base itself on different "flavors" of Rock. One can basically
choose one out of three:
@@ -41,15 +54,6 @@ What will be covered here:
## Installation {#install}
-
-As of today (June 2017), not all the software used in this guide has reached
-Rock mainline repositories. For this reason, one needs to start using the
-buildconf repository on GitHub's
-[`rock-gazebo/buildconf`](https://github.com/rock-gazebo/buildconf) instead of
-the default one at
-[`rock-core/buildconf`](https://github.com/rock-core/buildconf). This installation guide already reflects this.
-
-
Rock's current release is <%= config[:latest_release] %>, and requires **Ruby <%= config[:min_ruby_version] %> or later**
1. Install Ruby and verify that the version matches
@@ -73,31 +77,30 @@ Rock's current release is <%= config[:latest_release] %>, and requires **Ruby <%
~~~
4. Bootstrap your installation. This installs autoproj and checks out
- the build configuration, but does not check out packages
+ the main build configuration, but does not check out packages. As
+ [previously mentioned](#not_mainline), one must use the master flavor
+ of Rock to go through this documentation. Select the defaults for all
+ the proposed configuration options.
- - if you want to create a new workspace based on the latest release, do
-
- ~~~
- ruby autoproj_bootstrap \
- git https://github.com/rock-gazebo/buildconf \
- tag=<%= config[:latest_release] %>
- ~~~
-
- - if you want to use the `stable` or `master` flavors, do
-
- ~~~
- ruby autoproj_bootstrap \
- git https://github.com/rock-gazebo/buildconf
- ~~~
+ ~~~
+ ruby autoproj_bootstrap \
+ git https://github.com/rock-gazebo/buildconf
+ ~~~
- 5. Update and build the installation's default packages.
+ 5. Update and build the installation's default packages.Select the defaults for all
+ the proposed configuration options.
~~~
+ source env.sh
aup --all -k
amake --all -k
~~~
- 5. Important: as the build tool tells you, you **must** load the generated env.sh script at the end of the build !!! You must also do in new terminals before you can interact with the Rock installation
+
+You **must** remember to source the generated env.sh script at the end of the
+update !!! You must also do in new terminals before you can interact with the
+Rock installation
+{: .callout .callout-warning}
**Next**: [day-to-day interaction](day_to_day.html)