You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tuscany.apache.org by Simon Laws <si...@googlemail.com> on 2008/07/28 17:09:04 UTC
Squaring the circle - specs/tuscany features and user docs.
Looking through our user doc there is not much there that describes what
features are available and how to use them. Some have detail, e.g JMS [1],
some are non existent, e.g. Spring [2]. We (I) tend to get excited about
implementing spec features or implementing Tuscany extensions. Personally
when doing this I generally have a scenario in mind where I think the
feature would be useful. I think it would be good to record these scenarios
so others can read how we intended the software to work. I see we've started
doing this in a few places. Ant's JMS examples [1] are mini scenarios,
Luciano started adding scenarios to the Web2.0 roadmap ideas [3]. Also there
are some other scenarios associated with the databinding testing I think
Vamsi was doing [4].
I was thinking about some different types of scenario so I made some notes
[4]. I'm going to try and record Tuscany feature kind of info (maybe
directly into the user guide if no one objects) in an attempt to achieve the
following without having to think to hard about generating user docs
subsequently.
scenario -> helps define tests -> helps drive function -> most importantly
describes to the user how a feature works
Thoughts?
Simon
[1] http://tuscany.apache.org/sca-java-bindingjms.html
[2] http://tuscany.apache.org/sca-java-implementationspring.html
[3] http://tuscany.apache.org/sca-java-roadmap.html
[4] http://cwiki.apache.org/confluence/display/TUSCANYWIKI/Scenarios
Re: Squaring the circle - specs/tuscany features and user docs.
Posted by haleh mahbod <hm...@gmail.com>.
I had not noticed your reply in gmail. You update helps make the write up
clearer. Thank you.
On 8/1/08, Simon Laws <si...@googlemail.com> wrote:
>
>
>
> On Fri, Aug 1, 2008 at 3:31 PM, haleh mahbod <hm...@gmail.com> wrote:
>
>> In the write-up it says:
>>
>> When this module is loaded at runtime the contents of this file are made
>> generally available and hence in your composite you can use statements such
>> as.
>> Can you point out what is enabled in the composite as a result of the xml
>> definition above it?
>>
>> Thanks
>>
>>
>> On 8/1/08, Simon Laws <si...@googlemail.com> wrote:
>>>
>>>
>>>
>>> On Tue, Jul 29, 2008 at 12:20 AM, haleh mahbod <hm...@gmail.com>wrote:
>>>
>>>> This is a great idea. Scenarios put things in perspective.
>>>>
>>>>
>>>> On 7/28/08, Simon Laws <si...@googlemail.com> wrote:
>>>>>
>>>>> Looking through our user doc there is not much there that describes
>>>>> what features are available and how to use them. Some have detail, e.g JMS
>>>>> [1], some are non existent, e.g. Spring [2]. We (I) tend to get excited
>>>>> about implementing spec features or implementing Tuscany extensions.
>>>>> Personally when doing this I generally have a scenario in mind where I think
>>>>> the feature would be useful. I think it would be good to record these
>>>>> scenarios so others can read how we intended the software to work. I see
>>>>> we've started doing this in a few places. Ant's JMS examples [1] are mini
>>>>> scenarios, Luciano started adding scenarios to the Web2.0 roadmap ideas [3].
>>>>> Also there are some other scenarios associated with the databinding testing
>>>>> I think Vamsi was doing [4].
>>>>>
>>>>> I was thinking about some different types of scenario so I made some
>>>>> notes [4]. I'm going to try and record Tuscany feature kind of info (maybe
>>>>> directly into the user guide if no one objects) in an attempt to achieve the
>>>>> following without having to think to hard about generating user docs
>>>>> subsequently.
>>>>>
>>>>> scenario -> helps define tests -> helps drive function -> most
>>>>> importantly describes to the user how a feature works
>>>>>
>>>>> Thoughts?
>>>>>
>>>>> Simon
>>>>>
>>>>> [1] http://tuscany.apache.org/sca-java-bindingjms.html
>>>>> [2] http://tuscany.apache.org/sca-java-implementationspring.html
>>>>> [3] http://tuscany.apache.org/sca-java-roadmap.html
>>>>> [4] http://cwiki.apache.org/confluence/display/TUSCANYWIKI/Scenarios
>>>>>
>>>>>
>>>>
>>>>
>>>>
>>>
>>> Well I didn't get many to bite on this. I've added a definitions.xml page
>>> to the User Guide (as we need one) [1] but used it as an excuse to document
>>> a scenario we don't currently support correctly (
>>> https://issues.apache.org/jira/browse/TUSCANY-2499). Is this approach
>>> reasonable? The "scenario" could quite easily have gone in the JIRA but
>>> useful to have it somewhere and I just chose to put it in the User Guide in
>>> this case.
>>>
>>> I'm going to do a few more and I'll report back on how it goes.
>>>
>>> Simon
>>>
>>> [1]
>>> http://cwiki.apache.org/confluence/display/TUSCANY/SCA+Java+definitions.xml
>>>
>>>
>>
>>
>>
>
> Ok I added a line, take another look.
>
> Simon
>
>
Re: Squaring the circle - specs/tuscany features and user docs.
Posted by Simon Laws <si...@googlemail.com>.
On Fri, Aug 1, 2008 at 3:31 PM, haleh mahbod <hm...@gmail.com> wrote:
> In the write-up it says:
>
> When this module is loaded at runtime the contents of this file are made
> generally available and hence in your composite you can use statements such
> as.
> Can you point out what is enabled in the composite as a result of the xml
> definition above it?
>
> Thanks
>
>
> On 8/1/08, Simon Laws <si...@googlemail.com> wrote:
>>
>>
>>
>> On Tue, Jul 29, 2008 at 12:20 AM, haleh mahbod <hm...@gmail.com> wrote:
>>
>>> This is a great idea. Scenarios put things in perspective.
>>>
>>>
>>> On 7/28/08, Simon Laws <si...@googlemail.com> wrote:
>>>>
>>>> Looking through our user doc there is not much there that describes what
>>>> features are available and how to use them. Some have detail, e.g JMS [1],
>>>> some are non existent, e.g. Spring [2]. We (I) tend to get excited about
>>>> implementing spec features or implementing Tuscany extensions. Personally
>>>> when doing this I generally have a scenario in mind where I think the
>>>> feature would be useful. I think it would be good to record these scenarios
>>>> so others can read how we intended the software to work. I see we've started
>>>> doing this in a few places. Ant's JMS examples [1] are mini scenarios,
>>>> Luciano started adding scenarios to the Web2.0 roadmap ideas [3]. Also there
>>>> are some other scenarios associated with the databinding testing I think
>>>> Vamsi was doing [4].
>>>>
>>>> I was thinking about some different types of scenario so I made some
>>>> notes [4]. I'm going to try and record Tuscany feature kind of info (maybe
>>>> directly into the user guide if no one objects) in an attempt to achieve the
>>>> following without having to think to hard about generating user docs
>>>> subsequently.
>>>>
>>>> scenario -> helps define tests -> helps drive function -> most
>>>> importantly describes to the user how a feature works
>>>>
>>>> Thoughts?
>>>>
>>>> Simon
>>>>
>>>> [1] http://tuscany.apache.org/sca-java-bindingjms.html
>>>> [2] http://tuscany.apache.org/sca-java-implementationspring.html
>>>> [3] http://tuscany.apache.org/sca-java-roadmap.html
>>>> [4] http://cwiki.apache.org/confluence/display/TUSCANYWIKI/Scenarios
>>>>
>>>>
>>>
>>>
>>>
>>
>> Well I didn't get many to bite on this. I've added a definitions.xml page
>> to the User Guide (as we need one) [1] but used it as an excuse to document
>> a scenario we don't currently support correctly (
>> https://issues.apache.org/jira/browse/TUSCANY-2499). Is this approach
>> reasonable? The "scenario" could quite easily have gone in the JIRA but
>> useful to have it somewhere and I just chose to put it in the User Guide in
>> this case.
>>
>> I'm going to do a few more and I'll report back on how it goes.
>>
>> Simon
>>
>> [1]
>> http://cwiki.apache.org/confluence/display/TUSCANY/SCA+Java+definitions.xml
>>
>>
>
>
Ok I added a line, take another look.
Simon
Re: Squaring the circle - specs/tuscany features and user docs.
Posted by haleh mahbod <hm...@gmail.com>.
In the write-up it says:
When this module is loaded at runtime the contents of this file are made
generally available and hence in your composite you can use statements such
as.
Can you point out what is enabled in the composite as a result of the xml
definition above it?
Thanks
On 8/1/08, Simon Laws <si...@googlemail.com> wrote:
>
>
>
> On Tue, Jul 29, 2008 at 12:20 AM, haleh mahbod <hm...@gmail.com> wrote:
>
>> This is a great idea. Scenarios put things in perspective.
>>
>>
>> On 7/28/08, Simon Laws <si...@googlemail.com> wrote:
>>>
>>> Looking through our user doc there is not much there that describes what
>>> features are available and how to use them. Some have detail, e.g JMS [1],
>>> some are non existent, e.g. Spring [2]. We (I) tend to get excited about
>>> implementing spec features or implementing Tuscany extensions. Personally
>>> when doing this I generally have a scenario in mind where I think the
>>> feature would be useful. I think it would be good to record these scenarios
>>> so others can read how we intended the software to work. I see we've started
>>> doing this in a few places. Ant's JMS examples [1] are mini scenarios,
>>> Luciano started adding scenarios to the Web2.0 roadmap ideas [3]. Also there
>>> are some other scenarios associated with the databinding testing I think
>>> Vamsi was doing [4].
>>>
>>> I was thinking about some different types of scenario so I made some
>>> notes [4]. I'm going to try and record Tuscany feature kind of info (maybe
>>> directly into the user guide if no one objects) in an attempt to achieve the
>>> following without having to think to hard about generating user docs
>>> subsequently.
>>>
>>> scenario -> helps define tests -> helps drive function -> most
>>> importantly describes to the user how a feature works
>>>
>>> Thoughts?
>>>
>>> Simon
>>>
>>> [1] http://tuscany.apache.org/sca-java-bindingjms.html
>>> [2] http://tuscany.apache.org/sca-java-implementationspring.html
>>> [3] http://tuscany.apache.org/sca-java-roadmap.html
>>> [4] http://cwiki.apache.org/confluence/display/TUSCANYWIKI/Scenarios
>>>
>>>
>>
>>
>>
>
> Well I didn't get many to bite on this. I've added a definitions.xml page
> to the User Guide (as we need one) [1] but used it as an excuse to document
> a scenario we don't currently support correctly (
> https://issues.apache.org/jira/browse/TUSCANY-2499). Is this approach
> reasonable? The "scenario" could quite easily have gone in the JIRA but
> useful to have it somewhere and I just chose to put it in the User Guide in
> this case.
>
> I'm going to do a few more and I'll report back on how it goes.
>
> Simon
>
> [1]
> http://cwiki.apache.org/confluence/display/TUSCANY/SCA+Java+definitions.xml
>
>
Re: Squaring the circle - specs/tuscany features and user docs.
Posted by Simon Laws <si...@googlemail.com>.
On Tue, Jul 29, 2008 at 12:20 AM, haleh mahbod <hm...@gmail.com> wrote:
> This is a great idea. Scenarios put things in perspective.
>
>
> On 7/28/08, Simon Laws <si...@googlemail.com> wrote:
>>
>> Looking through our user doc there is not much there that describes what
>> features are available and how to use them. Some have detail, e.g JMS [1],
>> some are non existent, e.g. Spring [2]. We (I) tend to get excited about
>> implementing spec features or implementing Tuscany extensions. Personally
>> when doing this I generally have a scenario in mind where I think the
>> feature would be useful. I think it would be good to record these scenarios
>> so others can read how we intended the software to work. I see we've started
>> doing this in a few places. Ant's JMS examples [1] are mini scenarios,
>> Luciano started adding scenarios to the Web2.0 roadmap ideas [3]. Also there
>> are some other scenarios associated with the databinding testing I think
>> Vamsi was doing [4].
>>
>> I was thinking about some different types of scenario so I made some notes
>> [4]. I'm going to try and record Tuscany feature kind of info (maybe
>> directly into the user guide if no one objects) in an attempt to achieve the
>> following without having to think to hard about generating user docs
>> subsequently.
>>
>> scenario -> helps define tests -> helps drive function -> most importantly
>> describes to the user how a feature works
>>
>> Thoughts?
>>
>> Simon
>>
>> [1] http://tuscany.apache.org/sca-java-bindingjms.html
>> [2] http://tuscany.apache.org/sca-java-implementationspring.html
>> [3] http://tuscany.apache.org/sca-java-roadmap.html
>> [4] http://cwiki.apache.org/confluence/display/TUSCANYWIKI/Scenarios
>>
>>
>
>
Well I didn't get many to bite on this. I've added a definitions.xml page to
the User Guide (as we need one) [1] but used it as an excuse to document a
scenario we don't currently support correctly (
https://issues.apache.org/jira/browse/TUSCANY-2499). Is this approach
reasonable? The "scenario" could quite easily have gone in the JIRA but
useful to have it somewhere and I just chose to put it in the User Guide in
this case.
I'm going to do a few more and I'll report back on how it goes.
Simon
[1]
http://cwiki.apache.org/confluence/display/TUSCANY/SCA+Java+definitions.xml
Re: Squaring the circle - specs/tuscany features and user docs.
Posted by haleh mahbod <hm...@gmail.com>.
This is a great idea. Scenarios put things in perspective.
On 7/28/08, Simon Laws <si...@googlemail.com> wrote:
>
> Looking through our user doc there is not much there that describes what
> features are available and how to use them. Some have detail, e.g JMS [1],
> some are non existent, e.g. Spring [2]. We (I) tend to get excited about
> implementing spec features or implementing Tuscany extensions. Personally
> when doing this I generally have a scenario in mind where I think the
> feature would be useful. I think it would be good to record these scenarios
> so others can read how we intended the software to work. I see we've started
> doing this in a few places. Ant's JMS examples [1] are mini scenarios,
> Luciano started adding scenarios to the Web2.0 roadmap ideas [3]. Also there
> are some other scenarios associated with the databinding testing I think
> Vamsi was doing [4].
>
> I was thinking about some different types of scenario so I made some notes
> [4]. I'm going to try and record Tuscany feature kind of info (maybe
> directly into the user guide if no one objects) in an attempt to achieve the
> following without having to think to hard about generating user docs
> subsequently.
>
> scenario -> helps define tests -> helps drive function -> most importantly
> describes to the user how a feature works
>
> Thoughts?
>
> Simon
>
> [1] http://tuscany.apache.org/sca-java-bindingjms.html
> [2] http://tuscany.apache.org/sca-java-implementationspring.html
> [3] http://tuscany.apache.org/sca-java-roadmap.html
> [4] http://cwiki.apache.org/confluence/display/TUSCANYWIKI/Scenarios
>
>