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/ >
