review and correct the introduction and syskit basics main page

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.

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:
+
+<div class="panel panel-warning" markdown="1">
+<div class="panel-heading" markdown="1">
 
-We'll be following this flow (click on the steps title to go directly there):
+<a class="btn btn-warning" role="button" data-toggle="collapse" href="#under_the_hood" aria-expanded="false" aria-controls="under_the_hood">
+  Advanced
+</a><span class="advanced_description">This will hold the summary. Just click on "Advanced".</span>
+</div>
+<div class="collapse panel-body" markdown="1" id="under_the_hood">
+The details will be here.
+</div>
+</div>
 
-<%= 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:
+
+<table class="table">
+<thead>
+    <tr>
+    <th>What you will do</th>
+    <th>What Syskit concepts are covered</th>
+    </tr>
+</thead>
+<tbody>
+    <tr>
+    <td><%= link_to "Getting started", "getting_started.html" %></td>
+    <td>Bootstrapping a Syskit app with Gazebo and a SDF scene, running Gazebo and visualizing the scene</td>
+    </tr>
+    <tr>
+    <td><%= link_to "Creating an arm control network", "composition.html" %></td>
+    <td>Compositions</td>
+    </tr>
+    <tr>
+    <td><%= link_to "Holding position in the cartesian space", "constant_generator.html" %></td>
+    <td>Constant Generator, Profiles</td>
+    </tr>
+    <tr>
+    <td><%= link_to "Binding the component networks to the simulator", "devices.html" %></td>
+    <td>Devices</td>
+    </tr>
+    <tr>
+    <td><%= link_to "Running the networks", "deployment.html" %></td>
+    <td>Deployment and runtime</td>
+    </tr>
+</tbody>
+</table>
+
 That's all for now … [let's get started with our Syskit/Gazebo system](getting_started.html){:.btn .btn-primary}