I was thinking that if we use blogging as the primary way of describing samples, it's not even necessary to include a README in each and every sample, people can just search the blog knowing that information will be there (I'm trying to keep things as simple and interactive as possible -- to be honest, in most of the cases, I for one, am not checking the README files not even when I was first starting to look at Tuscany. They are hard to maintain and get out-dated quite easily).
One other advantage of blogging would be that comments containing questions and issues to which we'll respond will remain visible for everybody who's checking them out. When a user asks for clarification about a sample, I'm pretty sure we currently don't update the README to cover that. I'm just saying that it might help us be more open to our users, their needs, receive feedback from them and simplify maintainability (a blog post can always be edited or deleted and rewritten if major changes are done). IMO, this will improve the promotion of Tuscany especially with 2.0 approaching and help keep a better contact with users. Imagine that you're doing a nifty improvement on a module and update the sample. Nobody is checking the READMEs, a blog post is out there notifying people. I agree the distribution should have some kind of documentation on samples, I'm thinking that there should be a way of exporting the blog posts to a pdf format with a nice template which we can place in the samples/ directory right before doing a release (this way we don't end up with out dated information). There are a number of open source projects which have dedicated websites for samples, most of which I've seen are web frameworks (e.g Apache Wicket). It's not our case but I think we can do something similar and gain the benefits. On Thu, Feb 24, 2011 at 1:53 PM, Simon Laws <[email protected]>wrote: > On Wed, Feb 23, 2011 at 1:14 PM, Florian Moga <[email protected]> wrote: > > Yes, I was thinking that in this case READMEs would only contain some > > instructions on how to start the shell so it will basically be the same > > README copied in each and every folder. > > > > On Wed, Feb 23, 2011 at 3:02 PM, ant elder <[email protected]> wrote: > >> > >> On Wed, Feb 23, 2011 at 9:20 AM, Florian Moga <[email protected]> > wrote: > >> > As for doc, what do you think about the following idea? As soon as a > >> > sample > >> > graduates from contrib/ we can write a blog post explaining various > >> > things > >> > about it. It's much more interactive for both users and us. Also, the > >> > blog > >> > will probably get more attention and would be more complete. In this > >> > case, a > >> > top level README explaning how to start a sample and interact with it > >> > using > >> > the shell would be enough IMO. > >> > > >> > >> Is that suggestion to just have the blog posts and only a single top > >> level sample README? Blog posts seem like a fine idea but i do think > >> its good to have some sort of doc within each sample folder as its so > >> obvious there when a new user first looks at a sample. > >> > >> ...ant > > > > > > I think it's useful to have descriptive text distributed with the > samples otherwise it can be difficult to work out what the intended > function is. I've nothing against blogging about the samples but if we > commit to this a primary mechanism for detailed description then we > have the same problem we have with the web site in that people have to > follow a link to get to the details. > > Simon > > -- > Apache Tuscany committer: tuscany.apache.org > Co-author of a book about Tuscany and SCA: tuscanyinaction.com >
