stephen, this is by no means meant as an offence to you or some other
developer]
On Tue, Sep 28, 2010 at 1:59 PM, Stephen Roderick <kiwi [dot] net [..] ...> wrote:
[...]
> The documentation is fairly complete at
>
> http://orocos.org/wiki/rtt/rtt-20/real-time-logging/using-real-time-logging
>
> and looks to be up to date. I've attached a sample configuration file. Start a deployer using this as the site file, before you start your application
[...]
> I am definitely interested in feedback, so let me know how it goes or if you have more questions.
As a not-(yet-)2.0 user, this is not really my problem, so maybe I
should just shut up [*], but when looking at the website, it seems
*harder and harder* to find documentation as orocos evolves instead of
getting easier.
The entry page now mentions "Toolchain KDL BFL wiki". Now, when
entering the wiki, I get the following menu (slightly simplified)
KDL wiki
OCL wiki
RTT wiki
Toolchain
Now, supposed that (best case scenario) a newbie quickly got the point
that RTT and OCL are now a part of the toolchain subproject, how on
earth is he supposed to know that he should look for the documentation
of the real-time logging system in RTT wiki/the road to rtt-2.0?
Not to mention the fact that the five "figures" mention
RTT/BFL/KDL/*Components for Control* (being OCL)/ and Simulink
toolbox.
As a side note, I wanted to add a big fat disclaimer saying the
Simulink toolbox was rtt-1.x only, but I seem to have lost my edit
rights?
regards,
Klaas
ps.
2.0 Documentation [Was: logging in 2.0]
On Sep 28, 2010, at 09:51 , Klaas Gadeyne wrote:
> [Disclaimer: to get things very straight and avoid misunderstandings:
> stephen, this is by no means meant as an offence to you or some other
> developer]
None taken, but thanks anyway.
> On Tue, Sep 28, 2010 at 1:59 PM, Stephen Roderick <kiwi [dot] net [..] ...> wrote:
> [...]
>> The documentation is fairly complete at
>>
>> http://orocos.org/wiki/rtt/rtt-20/real-time-logging/using-real-time-logging
>>
>> and looks to be up to date. I've attached a sample configuration file. Start a deployer using this as the site file, before you start your application
> [...]
>> I am definitely interested in feedback, so let me know how it goes or if you have more questions.
>
> As a not-(yet-)2.0 user, this is not really my problem, so maybe I
> should just shut up [*], but when looking at the website, it seems
> *harder and harder* to find documentation as orocos evolves instead of
> getting easier.
>
> The entry page now mentions "Toolchain KDL BFL wiki". Now, when
> entering the wiki, I get the following menu (slightly simplified)
>
> KDL wiki
> OCL wiki
> RTT wiki
> Toolchain
>
> Now, supposed that (best case scenario) a newbie quickly got the point
> that RTT and OCL are now a part of the toolchain subproject, how on
> earth is he supposed to know that he should look for the documentation
> of the real-time logging system in RTT wiki/the road to rtt-2.0?
I thought the exact same thing when I went and found the link.
I don't remember whether the real-time logging made it in to RTT v1, but we should move the "using RT logging" to a wiki page that is linked to by v2 and by v1 documentation. For v1, it goes under OCL somewhere. For v2, where does it go? OCL? Toolchain?
Stephen
2.0 Documentation [Was: logging in 2.0]
>> On Tue, Sep 28, 2010 at 1:59 PM, Stephen Roderick <kiwi [dot] net [..] ...> wrote:
>> [...]
>>> The documentation is fairly complete at
>>>
>>> http://orocos.org/wiki/rtt/rtt-20/real-time-logging/using-real-time-logging
>>>
>>> and looks to be up to date. I've attached a sample configuration file. Start a deployer using this as the site file, before you start your application
>> [...]
>>> I am definitely interested in feedback, so let me know how it goes or if you have more questions.
>>
>> As a not-(yet-)2.0 user, this is not really my problem, so maybe I
>> should just shut up [*], but when looking at the website, it seems
>> *harder and harder* to find documentation as orocos evolves instead of
>> getting easier.
>>
>> The entry page now mentions "Toolchain KDL BFL wiki". Now, when
>> entering the wiki, I get the following menu (slightly simplified)
>>
>> KDL wiki
>> OCL wiki
>> RTT wiki
>> Toolchain
>>
>> Now, supposed that (best case scenario) a newbie quickly got the point
>> that RTT and OCL are now a part of the toolchain subproject, how on
>> earth is he supposed to know that he should look for the documentation
>> of the real-time logging system in RTT wiki/the road to rtt-2.0?
>
> I thought the exact same thing when I went and found the link.
>
> I don't remember whether the real-time logging made it in to RTT v1, but we should move the "using RT logging" to a wiki page that is linked to by v2 and by v1 documentation. For v1, it goes under OCL somewhere. For v2, where does it go? OCL? Toolchain?
Maybe there should be some clarification first of what is maintained
in the wiki and what is maintained in the xml documentation files.
This is probably the first hurdle that a user should take. As I can
imagine the RT logging (probably there will be other examples) will
evolve too and might be specific to a particular version, my first
thought (is most of the time just wrong :-) ), so maybe it's suits
better in the source tree?
The next thing seems indeed to be the structure of the wiki.
Hmm, did I just open pandora's box?
--
Orocos-Users mailing list
Orocos-Users [..] ...
http://lists.mech.kuleuven.be/mailman/listinfo/orocos-users
2.0 Documentation [Was: logging in 2.0]
On Sep 29, 2010, at 13:10 , Klaas Gadeyne wrote:
>>> On Tue, Sep 28, 2010 at 1:59 PM, Stephen Roderick <kiwi [dot] net [..] ...> wrote:
>>> [...]
>>>> The documentation is fairly complete at
>>>>
>>>> http://orocos.org/wiki/rtt/rtt-20/real-time-logging/using-real-time-logging
>>>>
>>>> and looks to be up to date. I've attached a sample configuration file. Start a deployer using this as the site file, before you start your application
>>> [...]
>>>> I am definitely interested in feedback, so let me know how it goes or if you have more questions.
>>>
>>> As a not-(yet-)2.0 user, this is not really my problem, so maybe I
>>> should just shut up [*], but when looking at the website, it seems
>>> *harder and harder* to find documentation as orocos evolves instead of
>>> getting easier.
>>>
>>> The entry page now mentions "Toolchain KDL BFL wiki". Now, when
>>> entering the wiki, I get the following menu (slightly simplified)
>>>
>>> KDL wiki
>>> OCL wiki
>>> RTT wiki
>>> Toolchain
>>>
>>> Now, supposed that (best case scenario) a newbie quickly got the point
>>> that RTT and OCL are now a part of the toolchain subproject, how on
>>> earth is he supposed to know that he should look for the documentation
>>> of the real-time logging system in RTT wiki/the road to rtt-2.0?
>>
>> I thought the exact same thing when I went and found the link.
>>
>> I don't remember whether the real-time logging made it in to RTT v1, but we should move the "using RT logging" to a wiki page that is linked to by v2 and by v1 documentation. For v1, it goes under OCL somewhere. For v2, where does it go? OCL? Toolchain?
>
> Maybe there should be some clarification first of what is maintained
> in the wiki and what is maintained in the xml documentation files.
> This is probably the first hurdle that a user should take. As I can
> imagine the RT logging (probably there will be other examples) will
> evolve too and might be specific to a particular version, my first
> thought (is most of the time just wrong :-) ), so maybe it's suits
> better in the source tree?
I'm a fan of the wiki here, as the turn around time for updating documentation on the website is far too long to be useful. Having said that, being able to write documentation directly into code examples and having that appear on the wiki would be very useful.
To use logging as an example, IMHO
1) API documentation goes in the source, and is updated online with each release
2) working example code (systems) with associated documentation goes in source (different code repository)
3) do we also do brief code examples on the wiki? I say yes, but I would like to be able to tie it to the working examples above. I think Qt does a wonderful job here with their online code examples. Maybe we just make sure that the doc's for 2) are on the website and updated as necessary?
> The next thing seems indeed to be the structure of the wiki.
>
> Hmm, did I just open pandora's box?
There was a lot of discussion about this at the developer's workshop. We came to some conclusions regarding website layout, but little in the way of overall structure. Sigh ... seems this is a very hard problem.
S
2.0 Documentation [Was: logging in 2.0]
On Tuesday 28 September 2010 17:12:09 Stephen Roderick wrote:
> On Sep 28, 2010, at 09:51 , Klaas Gadeyne wrote:
> > [Disclaimer: to get things very straight and avoid misunderstandings:
> > stephen, this is by no means meant as an offence to you or some other
> > developer]
>
> None taken, but thanks anyway.
>
> > On Tue, Sep 28, 2010 at 1:59 PM, Stephen Roderick <kiwi [dot] net [..] ...>
> > wrote: [...]
> >
> >> The documentation is fairly complete at
> >>
> >> http://orocos.org/wiki/rtt/rtt-20/real-time-logging/using-real-time-logg
> >> ing
> >>
> >> and looks to be up to date. I've attached a sample configuration file.
> >> Start a deployer using this as the site file, before you start your
> >> application
> >
> > [...]
> >
> >> I am definitely interested in feedback, so let me know how it goes or if
> >> you have more questions.
> >
> > As a not-(yet-)2.0 user, this is not really my problem, so maybe I
> > should just shut up [*], but when looking at the website, it seems
> > *harder and harder* to find documentation as orocos evolves instead of
> > getting easier.
> >
> > The entry page now mentions "Toolchain KDL BFL wiki". Now, when
> > entering the wiki, I get the following menu (slightly simplified)
> >
> > KDL wiki
> > OCL wiki
> > RTT wiki
> > Toolchain
> >
> > Now, supposed that (best case scenario) a newbie quickly got the point
> > that RTT and OCL are now a part of the toolchain subproject, how on
> > earth is he supposed to know that he should look for the documentation
> > of the real-time logging system in RTT wiki/the road to rtt-2.0?
>
> I thought the exact same thing when I went and found the link.
>
> I don't remember whether the real-time logging made it in to RTT v1, but we
> should move the "using RT logging" to a wiki page that is linked to by v2
> and by v1 documentation. For v1, it goes under OCL somewhere. For v2,
> where does it go? OCL? Toolchain?
AFAIK for v2, there should be only Toolchain, KDL, BFL, so I guess it goes to
Toolchain.
Ruben
> Stephen