The structure aside, could we have concise text file readme's that point to the website page that has the more detailed doc on the sample. Looking at other projects, eg servicemix, thats what they do and it seems to work well. And if necessary then we could also produce a single pdf including all the sample doc and include that in the distribution.
...ant On Wed, Sep 22, 2010 at 5:20 PM, kelvin goodson <[email protected]> wrote: > In moving things around and getting to where we now are I've had it in > mind that there would be a need for some good documentation, but the > structure needs to be pretty well settled before documentation that > hangs together can be created. I think we are nearly there, and I'd > like to get on with producing some docs. I think html readmes would > be good. There seems to be consensus that a flatter structure would > be preferable, so I plan to move the contents of tuscany-features into > the sca-features directory, The doc can then make such distinctions > clear in more verbose terms. > > Kelvin. > > On Tue, Sep 21, 2010 at 6:21 PM, Luciano Resende <[email protected]> wrote: >> On Tue, Sep 21, 2010 at 12:32 AM, Simon Laws <[email protected]> >> wrote: >>> On Tue, Sep 21, 2010 at 7:09 AM, ant elder <[email protected]> wrote: >>>> On Tue, Sep 21, 2010 at 6:55 AM, Luciano Resende <[email protected]> >>>> wrote: >>>>> On Mon, Sep 20, 2010 at 10:34 PM, ant elder <[email protected]> wrote: >>>>>> >>>>>> Ok, if there was a mainly flat structure what are your thoughts on >>>>>> then having at least one folder named something like "getting started" >>>>>> that groups some introductory samples to show new users how to get >>>>>> going with Tuscany so they aren't just confronted with a single folder >>>>>> with dozens of samples and not knowing where to begin? >>>>>> >>>>>> ...ant >>>>>> >>>>> >>>>> But then, we have the "Store getting started guide" on the website, >>>>> and currently store is listed at applications... but your suggestion >>>>> looks better, the less sub-folders the better, at least to my personal >>>>> preference >>>> >>>> Would a different name then alleviate the store guide issue - "first >>>> steps", "introduction", "Look here first" ...? >>>> >>>>> preference which you guys shouldn't care much for this sample >>>>> structure issue (at least for now) :). >>>> >>>> It would be good for users and the devs making these changes if we >>>> could agree a structure everyone can live with now and then not have >>>> to keep fiddling with it. Users aren't going to want samples moving >>>> around over releases, and it takes quite a bit of work moving to get >>>> the svn history, doc, build and release process all updated and >>>> working correctly so if the "(at least for now)" comment means you >>>> have something you're saving for later then now might be a better time >>>> to comment. >>>> >>>> ...ant >>>> >>> >>> >>> With a single flat folder structure it's very hard to distinguish between >>> >>> The samples I should look at first >>> The contributions demonstrating particular features of SCA >>> The launchers that demonstrate different ways of starting contributions >>> Other more fully formed applications that are not focused on particular >>> features >>> >>> I'm very comfortable with the small number of sub directories we have >>> now. Perhaps with the exception of the particular issue being >>> discussed of the potential confusion caused by sca-features and >>> tuscany-features. If that is solved by having a single sub-directory >>> to hold all of the feature contributions I'd be happy with that. >>> >>> Simon >>> >> >> How about we focus on documentation to clarify confusion, rather then >> expecting that a folder structure would solve the issue. Thinking as a >> user, I'd love to come to samples, see a html page that would list the >> samples and a high level description of them (similar to what we have >> on the readme today) and then be able to click on each sample and be >> able to get more info, maybe even a composition diagram, etc. This >> could well be done on the wiki as well, and exported as a PDF or HTML >> during release process. Anyway, just my 0.00002c and don't take it too >> seriously. >> >> >> >> -- >> Luciano Resende >> http://people.apache.org/~lresende >> http://twitter.com/lresende1975 >> http://lresende.blogspot.com/ >> >
