On Fri, Jan 9, 2009 at 11:48 AM, ant elder <[email protected]> wrote:
> > > On Fri, Jan 9, 2009 at 2:01 AM, haleh mahbod <[email protected]> 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
