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.

> - 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'.


> - I do not understand the meaning of the addition "(CORBA[v0.24.0])" in
>    3.1.1.

As noted above, it means this feature will appear in version 0.24.0.

> - "Persistent configuration" for the Properties: does this also mean that
>    the state of a controlle can be stored persistently?

I believe so. It is possible to use properties for every state variable in the 
control loop. A snapshot could be taken at any time to store a global state.
Orocos does not provide yet such a 'snapshot' component.

> - It might be useful to stress that the "realtime" in the "Realtime
>    Toolkit" stands for high determinism and thread-safety, and not in the
>    first place as a mandatory requirement to use an RTOS if one wants to
> use Orocos.

Good point.

> - "There are five distinct ways in which an Orocos component can be
>    interfaced: through its properties, events, methods, commands and data
>    flow ports." I would add here some sentence that explain that this level
>    of API has a lot of advantages for (realtime) control, because it offers
>    the services that all controlers want to use sooner or later, while
>    allowing to hide the nasty thread-safety implementation details behind
> the interface.

The advantages should be clear from the example that follows.

> - "Commands": I would add the clarification that a command cannot, in
>    general, be completely executed instantaneously, so the caller should
> not block and wait for its completion. But the TaskContext offers all
> functionalities to let the caller know about the progress in the execution
> of the command.

ok.

> - 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.

> - Figure 4 doesn't match very well with the three layers that you speak of
>    in the beginning of the document: RTT, Components, Application
> (Templates). This figure fits better in a developers-centered
> documentation, and not in this overview document, I think.

Ok.

> - I would _start_ with the application templates, because, as you say
>    yourself, this is also where the "normal user" will want to start
> working with Orocos.

Ok.

> - Section 4 "Vision" now reads like "blahblah"... I would throw it out, or
>    replace it by something more updated and condensed. (I know I wrote most
>    of this blahblah, but you should not save my feelings :-)
> - Also the history and bibliography are not appropriate for an overview
>    document, I think.

I'll move this stuff to the developer's manuals.

Thanks for the feedback,
Peter

-- 
Peter Soetens -- FMTC -- <http://www.fmtc.be>