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 <simonsl...@googlemail.com
<mailto:simonsl...@googlemail.com>> wrote:
On Wed, Feb 23, 2011 at 1:14 PM, Florian Moga <moga....@gmail.com
<mailto:moga....@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 <antel...@apache.org
<mailto:antel...@apache.org>> wrote:
>>
>> On Wed, Feb 23, 2011 at 9:20 AM, Florian Moga
<moga....@gmail.com <mailto:moga....@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
--
Apache Tuscany committer: tuscany.apache.org <http://tuscany.apache.org>
Co-author of a book about Tuscany and SCA: tuscanyinaction.com
<http://tuscanyinaction.com>
