On 24/02/2011 14:28, 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.
Florian,
I'm not against blogging, but there must be a description of how to run each sample contained in the
distribution along with each sample. There is nothing worse for a newbie than getting a
distribution with samples only to find that there is nothing telling them how to run the samples to
see what it takes to run an application with that runtime.
In my opinion, there should be readme material in the samples directories - that material can point
to blogs, but it should be possible to use the samples without ever seeing the blogs.
Yours, Mike.
