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 bring
about a decision? Can I as a committer stage a vote or does that have to be done by a PMC member?
Cheers,
Uli
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<[email protected]>
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: [email protected]
For additional commands, e-mail: [email protected]
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: [email protected]
For additional commands, e-mail: [email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
