You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tuscany.apache.org by haleh mahbod <hm...@gmail.com> on 2009/01/09 03:01:50 UTC
user guide - need your input please
Hi,
I have been cleaning up SCA Java user guide. The guide used to be a
'resting' place for all sort of information that did not work together. I
have changed it and unfortunately you'd have to look at the archive in order
to see how it originally looked. Half way through the cleanup process I
saved a copy into a wiki page called place holder so that you can see the
before look.
Here is the approach that I have taken and now that there is enough in place
I'd like to share and get your opinion.
1. Introduce SCA concepts
2. Use hands-on experience to learn SCA through samples. Start with simple
examples and grow them into more complicated one. Leverage Tuscany
samples/examples and refer to them directly instead of creating new
examples.
3. Create a cross ref to features/samples as a result of this
Please take a look at the Table Of Content on the user guide[1] and see if
this works.
If it looks OK, I'd like your help to develop the table of content. What
should be included in the TOC?
Once we have the TOC defined, we can fill in the rest of the information
together.
[1]:http://cwiki.apache.org/confluence/display/TUSCANY/SCA+Java+User+Guide
Thanks for your help,
Haleh
Re: user guide - need your input please
Posted by haleh mahbod <hm...@gmail.com>.
Hi,
If I understand it correctly these are features and plug points where users
need to know in order to use Tuscany SCA more efficiently. If this is the
case, user guide is a guide about how to use Tuscany SCA and this type of
information can go into the user guide as a section.
Haleh
On Fri, Jan 9, 2009 at 4:10 AM, Simon Laws <si...@googlemail.com>wrote:
>
>
> On Fri, Jan 9, 2009 at 11:48 AM, ant elder <an...@gmail.com> wrote:
>
>>
>>
>> On Fri, Jan 9, 2009 at 2:01 AM, haleh mahbod <hm...@gmail.com> wrote:
>>
>>> Hi,
>>> I have been cleaning up SCA Java user guide. The guide used to be a
>>> 'resting' place for all sort of information that did not work together. I
>>> have changed it and unfortunately you'd have to look at the archive in order
>>> to see how it originally looked. Half way through the cleanup process I
>>> saved a copy into a wiki page called place holder so that you can see the
>>> before look.
>>>
>>> Here is the approach that I have taken and now that there is enough in
>>> place I'd like to share and get your opinion.
>>> 1. Introduce SCA concepts
>>> 2. Use hands-on experience to learn SCA through samples. Start with
>>> simple examples and grow them into more complicated one. Leverage Tuscany
>>> samples/examples and refer to them directly instead of creating new
>>> examples.
>>> 3. Create a cross ref to features/samples as a result of this
>>>
>>> Please take a look at the Table Of Content on the user guide[1] and see
>>> if this works.
>>> If it looks OK, I'd like your help to develop the table of content. What
>>> should be included in the TOC?
>>>
>>> Once we have the TOC defined, we can fill in the rest of the information
>>> together.
>>>
>>> [1]:
>>> http://cwiki.apache.org/confluence/display/TUSCANY/SCA+Java+User+Guide
>>>
>>> Thanks for your help,
>>> Haleh
>>>
>>
>> I've started going though this and so far think its a big improvement,
>> I've made some trivial corrections and will continue going through it all
>> and thinking about what can go on the TOC and content but overall it looks
>> really good to me.
>>
>> ...ant
>>
>
> Hi Haleh
>
> I agree with Ant that this is much better than we had before. The kind of
> info that is on this TOC is good task driven introductory material. The
> extension guide sits alongside this well. I think we are missing some other
> reference info that doesn't seem to fit into this new TOC. For example, we
> have just been talking on the list about the different options you have for
> constricting a contribution so that your composites will run (there are some
> Tuscany specific options over an above SCA itself).
>
> At the higher level we have:
>
> User Guide
> Extension Guide
>
> So I see two options
>
> 1/ Rename "Extension Guide" to be some thing like "Feature and Extension
> Guide" to make it more natural to have entries like "contributions" in the
> table
> 2/ Have another page for reference material
> User Guide
> Extension Guide
> Refernece Guide
>
> I prefer 1 as it seems simpler.
>
> Regards
>
> Simon
>
Re: user guide - need your input please
Posted by Simon Laws <si...@googlemail.com>.
On Fri, Jan 9, 2009 at 11:48 AM, ant elder <an...@gmail.com> wrote:
>
>
> On Fri, Jan 9, 2009 at 2:01 AM, haleh mahbod <hm...@gmail.com> wrote:
>
>> Hi,
>> I have been cleaning up SCA Java user guide. The guide used to be a
>> 'resting' place for all sort of information that did not work together. I
>> have changed it and unfortunately you'd have to look at the archive in order
>> to see how it originally looked. Half way through the cleanup process I
>> saved a copy into a wiki page called place holder so that you can see the
>> before look.
>>
>> Here is the approach that I have taken and now that there is enough in
>> place I'd like to share and get your opinion.
>> 1. Introduce SCA concepts
>> 2. Use hands-on experience to learn SCA through samples. Start with simple
>> examples and grow them into more complicated one. Leverage Tuscany
>> samples/examples and refer to them directly instead of creating new
>> examples.
>> 3. Create a cross ref to features/samples as a result of this
>>
>> Please take a look at the Table Of Content on the user guide[1] and see if
>> this works.
>> If it looks OK, I'd like your help to develop the table of content. What
>> should be included in the TOC?
>>
>> Once we have the TOC defined, we can fill in the rest of the information
>> together.
>>
>> [1]:
>> http://cwiki.apache.org/confluence/display/TUSCANY/SCA+Java+User+Guide
>>
>> Thanks for your help,
>> Haleh
>>
>
> I've started going though this and so far think its a big improvement, I've
> made some trivial corrections and will continue going through it all and
> thinking about what can go on the TOC and content but overall it looks
> really good to me.
>
> ...ant
>
Hi Haleh
I agree with Ant that this is much better than we had before. The kind of
info that is on this TOC is good task driven introductory material. The
extension guide sits alongside this well. I think we are missing some other
reference info that doesn't seem to fit into this new TOC. For example, we
have just been talking on the list about the different options you have for
constricting a contribution so that your composites will run (there are some
Tuscany specific options over an above SCA itself).
At the higher level we have:
User Guide
Extension Guide
So I see two options
1/ Rename "Extension Guide" to be some thing like "Feature and Extension
Guide" to make it more natural to have entries like "contributions" in the
table
2/ Have another page for reference material
User Guide
Extension Guide
Refernece Guide
I prefer 1 as it seems simpler.
Regards
Simon
Re: user guide - need your input please
Posted by ant elder <an...@gmail.com>.
On Fri, Jan 9, 2009 at 2:01 AM, haleh mahbod <hm...@gmail.com> wrote:
> Hi,
> I have been cleaning up SCA Java user guide. The guide used to be a
> 'resting' place for all sort of information that did not work together. I
> have changed it and unfortunately you'd have to look at the archive in order
> to see how it originally looked. Half way through the cleanup process I
> saved a copy into a wiki page called place holder so that you can see the
> before look.
>
> Here is the approach that I have taken and now that there is enough in
> place I'd like to share and get your opinion.
> 1. Introduce SCA concepts
> 2. Use hands-on experience to learn SCA through samples. Start with simple
> examples and grow them into more complicated one. Leverage Tuscany
> samples/examples and refer to them directly instead of creating new
> examples.
> 3. Create a cross ref to features/samples as a result of this
>
> Please take a look at the Table Of Content on the user guide[1] and see if
> this works.
> If it looks OK, I'd like your help to develop the table of content. What
> should be included in the TOC?
>
> Once we have the TOC defined, we can fill in the rest of the information
> together.
>
> [1]:http://cwiki.apache.org/confluence/display/TUSCANY/SCA+Java+User+Guide
>
> Thanks for your help,
> Haleh
>
I've started going though this and so far think its a big improvement, I've
made some trivial corrections and will continue going through it all and
thinking about what can go on the TOC and content but overall it looks
really good to me.
...ant