Good point Tom. We need to structure the documentation in such a way to align it with major releases.
Can we agree on the audience for the documentation before we start with content? Here is a proposal: Audience 1: Users - Users develop applications on top of Tuscany and don't necessarily want to look into the code. - Users would work off of a published release. For example, download M2 and write applications on top of it. - Interesting documents might be: user manual (SCA and Tuscany value add), guides for developing simple and more complex applications, what else? - Concept of attaching documents to releases is important here. Documents are not live and rather are based on releases. For example, we will have user manual for version x and an enhanced document for version y. Audience 2: Tuscany Extension developers - Uses Tuscany Core as a black box - Needs to know about extension points (SPIs) and how to add extensions - Would need to know how to build extensions and test - Would probably want to work off of the latest code, so documents tend to be live documents. - Interesting documents might be: how to setup development environment, how to develop extensions with simple examples, architecture document, development guidelines (how to provide patches, etc) Audience 3: Tuscany Developers - Needs to know how to build Tuscany - Interested in architecture document and design documents that are live documents (change as the code changes) - Interesting documents might be: architecture document, how to setup development environment and test, Code structure, etc. If in agreement, then we have 3 parallel threads. I was suggesting that we start with category 1 although all of this can happen in parallel with everyone helping. We just need to structure them correctly. Haleh On 2/9/07, Tom Seelbach <[EMAIL PROTECTED]> wrote:
Related to your discussion, the Geronimo team has organized their wiki into multiple spaces: http://cwiki.apache.org/confluence/display/geronimo/Geronimo+cwiki+documentation+architecture -Tom Shelita Overton wrote: > I see what you are saying Dan. > > I like the side bar on the CFX wiki ( http://cwiki.apache.org/CXF/ ) > as you > have mentioned. > > As for another example for layout/organization, I was looking at the > confluence wiki page for documenation ... i also like how they have their > intial page setup. > > http://confluence.atlassian.com/display/DOC/Confluence+Documentation+Home > > I definetly think we should have one ititial documenation page, allow > users > to select which guide, ie User Guide vs Developer Guide. > > > On 2/9/07, Dan Murphy <[EMAIL PROTECTED]> wrote: >> >> Humm, one thing just stuck me using this wiki is that although >> heirarchical >> in some ways... all documents sit in a single space (as they do in many >> wikis... although interestingly I don't think the old one did). >> >> This can lead to some interesting side effects.. for example >> http://cwiki.apache.org/confluence/display/TUSCANY/Building+your+own >> is a >> child document of the user guide.. but it sits in the top level. This >> isn't >> going to be a problem for all documents, but it does mean that there can >> only be one /TUSCANY/Introduction document or one TUSCANY/Building >> document. >> >> To overcome this limitation we can do one of the following: >> Seperate into multiple spaces (eg TUSCANYUserGuide/,,, and >> TUSCANYCommitterGuide) this has the plus of allowing two "introduction" >> pages, one in each space, but on the downside it means that there is no >> longer a single TUSCANY space - although TUSCANY could link to >> TUSCANYUser >> etc >> Or, We prefix pages - which can obviously be a little messy. >> >> WDYT ? Looking at the top level space, it seems like other have gone >> for a >> multiple but linked spaces... see http://cwiki.apache.org/CXF/ >> >> Thought I should raise this now to make sure people are aware... >> >> Cheers, >> Dan >> >> On 08/02/07, Simon Laws <[EMAIL PROTECTED]> wrote: >> > >> > On 2/8/07, Dan Murphy <[EMAIL PROTECTED]> wrote: >> > > >> > > Hi, >> > > >> > > Nope I hadn't done it yet, I wanted to get a go ahead 1st :) >> > > I'll create them now but won't get a chance to put much / any >> content >> in >> > > b4 >> > > tomorrow... so feel free to pick a page and start work on it... >> we can >> > > then >> > > all contribute drafts and then use the commenting system in the wiki >> tro >> > > refine it later... >> > > >> > > Everyone ok with this ? >> > > >> > > Start page is >> > > http://cwiki.apache.org/confluence/display/TUSCANY/User+Guide >> > > >> > > Cheers, >> > > Dan >> > > >> > > >> > > >> > > On 08/02/07, Simon Laws <[EMAIL PROTECTED]> wrote: >> > > > >> > > > On 2/8/07, Shelita Overton <[EMAIL PROTECTED]> wrote: >> > > > > >> > > > > Hi Dan, >> > > > > >> > > > > I think this is a great start. I think it is safe to go ahead >> and >> > > create >> > > > > this structure. This will definitely help to avoid >> > > > duplication. Thanks! >> > > > > >> > > > > >> > > > > On 2/8/07, Dan Murphy <[EMAIL PROTECTED]> wrote: >> > > > > > >> > > > > > Hi Shelita, >> > > > > > >> > > > > > I'd like to partner with you on writing some documentation and >> had >> > > > also >> > > > > > started a page on the wiki @ >> > > > > > >> > > > > > >> > > > > >> > > >> > >> http://cwiki.apache.org/confluence/display/TUSCANY/Building+SCA+for+Javawhich >> >> > > > >> > > > > > has some overlap with Raymonds more recent addition. >> > > > > > >> > > > > > How about we break the getting starting down into a number of >> > > smaller >> > > > > > pages >> > > > > > so we can work on them more easily. I propose: >> > > > > > >> > > > > > User Guide >> > > > > > + Getting Tuscnay's Java SCA >> > > > > > + Choosing between a package runtime and building >> your >> > > own >> > > > > > + Downloading and installing a release >> > > > > > + (use the the approach I'm experimenting with @ >> > > > > > >> > > >> http://www.mail-archive.com/tuscany-dev%40ws.apache.org/msg13707.html >> > > > ) >> > > > > > + Setting up a build environment >> > > > > > + Choosing a source / understanding the source tree >> > > > > > + Building - which bits to build >> > > > > > + Debugging build issues >> > > > > > + Build tips (eg. use of mvn -fn to continue >> > > building >> > > > > > despite test case failures) >> > > > > > + Setting up an "SCA Developer" environment (cover both >> command >> > > > line >> > > > > > and >> > > > > > IDEs (Eclipse and others)) suitable for a user of Tuscany (as >> > > opposed >> > > > to >> > > > > a >> > > > > > developer of) >> > > > > > + Developing a simple SCA composite containing a single >> > component >> > > > > > + Initial project setup (is there an alternative to >> > maven >> > > > ?) >> > > > > > + Developing a simple component >> > > > > > + Unit testing and debugging a component >> > > > > > + Composing components into composites >> > > > > > + Exposing the composite to the outside world >> (define >> > the >> > > > > > service binding) >> > > > > > + Web Services, JMS etc >> > > > > > + Resolving dependencies not contained in the >> composite >> > > > > > (defining the reference bindings) >> > > > > > + Web Services, JMS - others ? >> > > > > > + Reusing components in composites >> > > > > > + Deploying to server runtime (eg. tomcat & geronimo ?) >> > > > > > ( + Managing / monitor / changing components & composites ) >> > > > > > ... >> > > > > > >> > > > > > I think it might also bring up some interesting things to >> > > consider... >> > > > > for >> > > > > > example, "How can I reuse components in a composite without >> > copying >> > > it >> > > > >> > > > > > from >> > > > > > another project ?" >> > > > > > >> > > > > > If folks agree with this structure (or similar) then I'll go >> ahead >> > > and >> > > > > > create it - I think it would be a good idea to agree some >> > structure >> > > > > > upfront >> > > > > > to avoid duplication (which seems likely unless we have one >> > author). >> > > > > > >> > > > > > WDYT ? >> > > > > > Dan >> > > > > > >> > > > > > On 07/02/07, Raymond Feng < [EMAIL PROTECTED]> wrote: >> > > > > > > >> > > > > > > Hi, >> > > > > > > >> > > > > > > I just added a draft @ >> > > > > > > >> > http://cwiki.apache.org/confluence/display/TUSCANY/Getting+Started >> > > . >> > > > We >> > > > > > > might >> > > > > > > be able to use it as a starting point and add more meat into >> it >> > to >> > > > > help >> > > > > > > new >> > > > > > > users understand the basic concepts, steps and tools to >> develop >> > a >> > > > > simple >> > > > > > > SCA >> > > > > > > application with Tuscany. >> > > > > > > >> > > > > > > Thanks, >> > > > > > > Raymond >> > > > > > > >> > > > > > > ----- Original Message ----- >> > > > > > > From: "haleh mahbod" <[EMAIL PROTECTED]> >> > > > > > > To: < [email protected]> >> > > > > > > Sent: Wednesday, February 07, 2007 11:33 AM >> > > > > > > Subject: Re: Suggestions for Tuscany SCA documenation? >> > > > > > > >> > > > > > > >> > > > > > > > Hi Shelita, >> > > > > > > > Welcome to Tuscany. We definitly need help with >> documentation >> > :) >> > > > > > > > >> > > > > > > > A starting point might be a user giude on how to >> develop a >> > > simple >> > > > > SCA >> > > > > > > > application. This document can then incrementally grow >> > to cover >> > > > > more >> > > > > > > > advanced topics. >> > > > > > > > >> > > > > > > > Another project might be to work on an SCA user doc with >> > > examples. >> > > > > > This >> > > > > > > > would provide a quick reference to SCA rather than >> requiring >> > > > people >> > > > > to >> > > > > > > > read >> > > > > > > > all the specifications. >> > > > > > > > >> > > > > > > > I would be happy to join you in this effort. We can start >> > using >> > > > > > > Confluence >> > > > > > > > Wiki to work on the documents. >> > > > > > > > >> > > > > > > > Does the 'user guide' sound like a good starting point for >> > you? >> > > > > > > > >> > > > > > > > What do others think? >> > > > > > > > >> > > > > > > > Haleh >> > > > > > > > >> > > > > > > > >> > > > > > > > On 2/7/07, Rick Rineholt <[EMAIL PROTECTED]> wrote: >> > > > > > > >> >> > > > > > > >> Hello, >> > > > > > > >> If your totally new to SCA/Tuscany having a fresh pair of >> > eyes >> > > > > > looking >> > > > > > > >> at first understanding SCA, looking at our website how >> easy >> > it >> > > is >> > > > >> > > > > to >> > > > > > > >> find resources, how well those were, then moving on to >> the >> > > > samples >> > > > > in >> > > > > > > M2 >> > > > > > > >> and then try and understand how contribute to Tuscany >> itself >> > > and >> > > > > > along >> > > > > > > >> the way provide feedback and updates can be always >> > > beneficial. I >> > > > > > think >> > > > > > > >> that's ground anyone first starting out would initially >> have >> > to >> > > > > cover >> > > > > > > to >> > > > > > > >> some degree or another. >> > > > > > > >> If your not new, you'll need to give some background and >> > where >> > > > your >> > > > > > > >> interests are in general. >> > > > > > > >> . >> > > > > > > >> Shelita Overton wrote: >> > > > > > > >> > Hi I would like to help with creating some documenation >> for >> > > > > Tuscany >> > > > > > > >> > SCA... >> > > > > > > >> > Does anyone have any suggestions on what should be >> covered >> > > > first? >> > > > > > > >> > Priority? >> > > > > > > >> > Any content that could be used as a starting point? >> > > > > > > >> > >> > > > > > > >> > ~Shelita Overton >> > > > > > > >> > >> > > > > > > >> >> > > > > > > >> >> > > > > > > >> >> > > > > >> > --------------------------------------------------------------------- >> > > > > > > >> To unsubscribe, e-mail: >> [EMAIL PROTECTED] >> > > > > > > >> For additional commands, e-mail: >> > [EMAIL PROTECTED] >> > > > > > > >> >> > > > > > > >> >> > > > > > > > >> > > > > > > >> > > > > > > >> > > > > > > >> > > > >> --------------------------------------------------------------------- >> > > > > > > To unsubscribe, e-mail: >> [EMAIL PROTECTED] >> > > > > > > For additional commands, e-mail: >> [EMAIL PROTECTED] >> > > > > > > >> > > > > > > >> > > > > > >> > > > > >> > > > Hi Dan >> > > > >> > > > Have you already created this? If so I'll go edit ti myself, If >> not >> I >> > > > suggest we have a section >> > > > >> > > > "Running the samples" >> > > > >> > > > >> > > > coming after the first section which describes how to get the >> code. >> If >> > I >> > > > remember correctly there is some automation of this already in >> > > place but >> > > > it >> > > > would be good to have some descriptive text and suggestions about >> > which >> > > > ones >> > > > to try first and also the kind of things that might go wrong. >> > > > >> > > > Simon >> > > > >> > > >> > Great Dan, go for it. >> > >> > Simon >> > >> > --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
