tuscany-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ant elder <ant.el...@gmail.com>
Subject Re: 2.0 Beta2 samples (was: [VOTE] Release Tuscany SCA 2.0 Beta2 RC2)
Date Mon, 28 Feb 2011 07:59:08 GMT
On Thu, Feb 24, 2011 at 3:58 PM, Simon Nash <nash@apache.org> wrote:
> Florian Moga wrote:
>>
>> 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.
>>
> I think it's important that samples include intructions for running them.
> If we can also blog about new samples before we release them, that's
> good too.
>
> The purpose of samples is to make it easy for new users to understand
> how to use Tuscany by running the sample.  If the instructions aren't
> included with the sample, the user has to find the instructions and
> make sure that they have the right version of instructions for this
> version of the sample.  This adds an additional step to what a new user
> needs to do.
>
> Also, as samples move through multiple releases, having instructions
> in a separate place from the sample increases the chance of a user
> accidentally getting the wrong version of the instructions.
>
>  Simon
>
>>
>> On Thu, Feb 24, 2011 at 1:53 PM, Simon Laws <simonslaws@googlemail.com
>> <mailto:simonslaws@googlemail.com>> wrote:
>>
>>    On Wed, Feb 23, 2011 at 1:14 PM, Florian Moga <moga.flo@gmail.com
>>    <mailto:moga.flo@gmail.com>> 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 <antelder@apache.org
>>    <mailto:antelder@apache.org>> wrote:
>>     >>
>>     >> On Wed, Feb 23, 2011 at 9:20 AM, Florian Moga
>>    <moga.flo@gmail.com <mailto:moga.flo@gmail.com>> 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

I think i also like having a readme within each sample that gives at
least some minimal description of what the sample does and how to run
it, but that doesn't mean we couldn't also blog about it or have doc
on the website or something else too.

   ...ant

Mime
View raw message