Re: Orocos 'Overview' document updated

> On Wednesday 08 March 2006 23:17, Herman Bruyninckx wrote:
> > On Tue, 7 Mar 2006, Peter Soetens wrote:
> > > In the course of the release next week, the non-technical overview
> > > documentation has been updated with figures illustrating my previous
> > > 'Roadmap' mail and a high level example of an 'Orocos Component'.
> > >
> > > HTML version:
> > > <http://people.mech.kuleuven.be/~psoetens/orocos/doc/orocos-overview.html>
> >
> > Some remarks (the most important ones being the ones that suggest to remove
> > stuff :-):
> > - I think this document is too robot-centered, reflecting the status of two
> >    year ago. The project now has more mature content, for more than "just"
> >    robot applications.
> 
> I believe using a 'robot' is an ideal example to _explain a new user_ what a 
> "component" looks like in Orocos. It's concrete, people are familiar with it. 
> An improved documentation of the _other_ Orocos components in the 'component 
> manuals' will broaden the insights of the interested user anyway.

I think Herman's remarks about being robot centered are related to
Section 1 "What is orocos" and Section 2 "Target audience" (e.g. the
second sentence about the project's aim).  I agreewith him on that
matter,  while I have no problem using concrete "robot examples" for
making things more practical.

Section 2, item 3: Application builders
In the first sentence, you state they are building "particular
applications".  Two sentences later however, you state that
<quote>
An example Orocos application is the Orocos Control Kernel, which
provides an application framework for (motion) control, with a set of
components which implement control or planning algorithms.
</quote>
"An application which provides an application framework" is something I
don't understand.

In the same paragraph you use the word "architecture".  I guess you
mean with that word something like "how components are organized
together into an application (i.e.~e.g.~connected to each other)?  I
think this (and probably other terms too) should become a link to the
glossary.


> > - The introduction of the section "3. Orocos Project Software Overview"
> >    is old, to say the least.
> 
> It clearly separates this project from other projects which name(d) themselves 
> "Orocos" as well. I do not understand how this can be 'old'.

See my previous off-list mail about the orocos@faw link being dead
(that's even worse than old :-).  And note the official name of orca
is now orca2.

- Figure 2 does not look too clear when printed with a non-color
printer :-)


> > - Figure 3 is not really about "implementation", is it?
> 
> It is too abstract, but technically, implementation is done with state 
> machines and it 'shows' a state machine... needs work.

Indeed, I didn't understand this either. :-)
You also use the term "peer" in this figure, which is not (yet)
explained I guess...

- Section 3.1.5:  After the ambiguity between application (1) and
   application framework (2), a third term is introduced:  application
   templates (3).  I guess you mean the same thing with (2) and (3),
   and as framework is already used in another context in this intro, I
   suggest to remove the term "application framework" and replace it by
   (3).

- nothing more than -> nothing but ?

Klaas