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
