tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sebastian Hennebrueder <use...@laliluna.de>
Subject Re: documentation improvements
Date Mon, 01 Mar 2010 08:42:40 GMT
Piero Sartini schrieb:
>> Considering b) I don't know what is more efficient. Letting people access
>> the Wiki and look through the changes or applying patches to files and
>> looking at the changes with normal IDE tooling or on the command line.
> 
> The problem I see is that if people just want to contribute
> documentation, they need to checkout the files, make their changes in
> a format that is not known and create a patch afterwards. That's too
> much effort in my oppinion - we should make it as easy as possible for
> people to contribute. My feeling is that more people would contribute
> if we use a good wiki like confluence - after all it is a well known
> tool, used by a lot of projects.
> 
> It's totally possible that this tool Sebastian proposed is better and
> more powerful. For sure it is geekier. But in my oppinion it is not
> the right tool to make a community work together on documentation.
> 
>            Piero
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
> For additional commands, e-mail: dev-help@tapestry.apache.org
> 
> 
Some people (at least I) would have to learn Confluence Wiki language as 
well. It might be because I am unexperienced with confluence but I found 
that it was slightly tricky to get everything formatted as I wanted, 
when I fixed minor things in the Wiki.

We need to keep in mind that just contributing won't work. Unexperienced 
people will overlook options or best practises while fixing the 
documentation. As a consequence, we need to verify changes and define a 
work flow. I am not sure how much contributing we get, if the process is 
faster. I use the current Wiki very little as documenation source and 
always with care, as not all documents are up to date and have different 
quality. I prefer the core doc and the code over the current Wiki area.

Considering the code, we have this work flow established naturally as 
only core commiters can submit patches. For the documentation we might 
need a team of core committers + documentation committers who do the 
same job. This is required for both approaches and not an argument for 
or against any of the solutions.

Well, we should continue the discussion to balance the pros and cons. 
Meanwhile, I could try the Jekyll approach for TapX. Then we could have 
a look how it works in practice. On the other side, we could get some 
demo working for confluence as well.

-- 
Best Regards / Viele Grüße

Sebastian Hennebrueder
-----
Software Developer and Trainer for Hibernate / Java Persistence
http://www.laliluna.de



---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org


Mime
View raw message