tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ulrich Stärk <...@spielviel.de>
Subject Re: documentation improvements
Date Mon, 01 Mar 2010 15:24:48 GMT
Of course it would be nice to show people that we eat our own dog food. We would need to set
up the 
whole infrastructure (servlet container, database, backup, etc.) ourselves though. Don't 
underestimate the effort for that.

I still prefer the wiki approach though:

- it is well supported at the ASF (backups, updates, etc.)
- changes are published to our website automatically
- nice interface with rich text editor instead of cryptic XML
- we can include the generated content in our releases

But I also see Howards point about having the docs under source control. Maybe we can split
the two 
things up: Put the website on confluence so as to being able to quickly make changes and aggregate

the documentation into ONE exhaustive user guide and have that in version control and copied
over to 
the main website at intervals or on changes.

When this discussion is over and everybody has been heared, what would be the right way to
about a decision? Can I as a committer stage a vote or does that have to be done by a PMC



On 01.03.2010 10:55, Christophe Cordenier wrote:
> Hi,
> Sorry to jump into the thread like this, but we have started to develop
> 'wooki' a few months ago. This tool aims to provide a tool in the spirit of
> the Django book at http://www.djangobook.com/en/1.0/ with many other
> features.
> We are currently focusing on social features and import/export format. All
> the chapter of a book have a revision number, and it would be easy to extend
> this to the entire book for version management. Also we can implement some
> right management based on roles and give contributor, comment rights,
> review...
> Wooki still need some development but we are doing our best to provide it to
> community as a tool but also as a full Tapestry application demonstration
> with intermediate release.
> Note that this tool has the great advantage to be developed with Tapestry,
> so if there are people who are interested to see one day some Tapestry
> documentation written with a tool developed with Tapestry then checkout the
> source at http://github.com/robink/wooki
> A demonstration of the first alpha version is available @wookicentral.com,
> the 0.2 will be deployed soon with Feed feature and a pretty PDF print.
> Best Regards,
> Christophe Cordenier.
> 2010/3/1 Sebastian Hennebrueder<usenet@laliluna.de>
>> 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

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

View raw message