You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tapestry.apache.org by Piero Sartini <li...@pierosartini.de> on 2010/03/01 01:25:17 UTC
Re: documentation improvements
> 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
Re: documentation improvements
Posted by "Thiago H. de Paula Figueiredo" <th...@gmail.com>.
On Mon, 01 Mar 2010 10:52:41 -0300, Christophe Cordenier
<ch...@gmail.com> wrote:
> Hi,
Hi!
> We have switched from FOP to Flying saucer that allows us to stylize the
> PDF via a CSS file, also Bookmarks generation has been made easier.
> Demonstration still uses FOP but HEAD revision uses FlyingSaucer.
Nice! I'm writing a Tapestry textbook using HTML, CSS and PrinceXML as the
PDF rendering and I want to test Flying Saucer's PDF rendering soon. :)
> Note that the Generic DAO has been inspired from your implementation @
> arsmarchina.com :)
Cool! But my website is arsmachina.com.br. I don't sell antique scientific
instruments. :)
--
Thiago H. de Paula Figueiredo
Independent Java, Apache Tapestry 5 and Hibernate consultant, developer,
and instructor
Owner, software architect and developer, Ars Machina Tecnologia da
Informação Ltda.
http://www.arsmachina.com.br
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org
Re: documentation improvements
Posted by Christophe Cordenier <ch...@gmail.com>.
Hi,
We have switched from FOP to Flying saucer that allows us to stylize the PDF
via a CSS file, also Bookmarks generation has been made easier.
Demonstration still uses FOP but HEAD revision uses FlyingSaucer.
Note that the Generic DAO has been inspired from your implementation @
arsmarchina.com :)
Best Regards,
Christophe Cordenier.
2010/3/1 Thiago H. de Paula Figueiredo <th...@gmail.com>
> On Mon, 01 Mar 2010 06:55:32 -0300, Christophe Cordenier <
> christophe.cordenier@gmail.com> wrote:
>
> Hi,
>>
>
> Hi!
>
>
> 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...
>>
>
> I really, really like this idea!
>
>
> 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.
>>
>
> Nice!
>
>
> 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
>>
>
> I'm also building my own blog engine in Tapestry with the same goals as
> Wooki: run it in production and to serve as an example.
> I'll take a look at Wooki as soon as I finish the Tapestry textbook I'm
> writing . . . Seems very interesting. :)
> How is the PDF export done? Flying Saucer?
>
> --
> Thiago H. de Paula Figueiredo
> Independent Java, Apache Tapestry 5 and Hibernate consultant, developer,
> and instructor
> Owner, software architect and developer, Ars Machina Tecnologia da
> Informação Ltda.
> http://www.arsmachina.com.br
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
> For additional commands, e-mail: dev-help@tapestry.apache.org
>
>
--
Regards,
Christophe Cordenier.
Developer of wooki @wookicentral.com
Re: documentation improvements
Posted by "Thiago H. de Paula Figueiredo" <th...@gmail.com>.
On Mon, 01 Mar 2010 06:55:32 -0300, Christophe Cordenier
<ch...@gmail.com> wrote:
> Hi,
Hi!
> 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...
I really, really like this idea!
> 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.
Nice!
> 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
I'm also building my own blog engine in Tapestry with the same goals as
Wooki: run it in production and to serve as an example.
I'll take a look at Wooki as soon as I finish the Tapestry textbook I'm
writing . . . Seems very interesting. :)
How is the PDF export done? Flying Saucer?
--
Thiago H. de Paula Figueiredo
Independent Java, Apache Tapestry 5 and Hibernate consultant, developer,
and instructor
Owner, software architect and developer, Ars Machina Tecnologia da
Informação Ltda.
http://www.arsmachina.com.br
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org
Re: documentation improvements
Posted by Sebastian Hennebrueder <us...@laliluna.de>.
IMHO, we should provide a proof of concept for the solutions to let doc
writers check the approaches. This will show, if the approach is fast
and can be easily deployed and packaged.
Ulrich Stärk schrieb:
> 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<us...@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
>
>
--
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
Re: documentation improvements
Posted by Ulrich Stärk <ul...@spielviel.de>.
The problem with a collaborative approach to writing Tapestrys official
documenation is that every contribution has to be made intentionally and
prove of this intention has to be provided. For committers that means
signing a CLA. The same would hold for documentation contributors. We
can't just have everyone write the official documentation. And if you
drop point c) and the truely collaborative part, you and up with a wiki
like confluence.
Uli
Renger Wilde schrieb:
> I really like the collaborative, componentized documentation development
> concepts advocated at Christophe Cordenier's http://wookicentral.com/demo/
> Wooki site. The powerful concepts he's got include:
>
> a. Easy collaborative drafting and editing of a componentized, modular
> document (wiki-style)
> b. Generate PDF on-demand
> c. Written in Tapestry
>
> I also strongly agree that we should separate out reference documentation
> that can be auto-generated (e.g. Javadoc and the like) from best-practice,
> how-to, and examples documentation. They are two completely different beasts
> - with different committers (skills, tools, needs) and different
> content-sources (meta-data in source files .vs. stuff in people's brains)
> and different user needs (reference .vs. big-picture process, general
> concepts, how-tos, examples).
>
> These concept-driven documentation types are the ones most sorely missing
> from the Tapestry world, and that, in my opinion, is where the focus of the
> next documentation effort should be. Why? Because that lack is currently the
> single biggest impediment to expanding Tapestry's market share (and vitality
> as a product) that we currently face.
>
> I recognize that Christophe's product is in its early stages of development,
> but I see substantial promise in his work, and I encourage all of us to give
> it a look. He's come a great big long way in a few short months.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org
Re: documentation improvements
Posted by Renger Wilde <bu...@yahoo.com>.
I really like the collaborative, componentized documentation development
concepts advocated at Christophe Cordenier's http://wookicentral.com/demo/
Wooki site. The powerful concepts he's got include:
a. Easy collaborative drafting and editing of a componentized, modular
document (wiki-style)
b. Generate PDF on-demand
c. Written in Tapestry
I also strongly agree that we should separate out reference documentation
that can be auto-generated (e.g. Javadoc and the like) from best-practice,
how-to, and examples documentation. They are two completely different beasts
- with different committers (skills, tools, needs) and different
content-sources (meta-data in source files .vs. stuff in people's brains)
and different user needs (reference .vs. big-picture process, general
concepts, how-tos, examples).
These concept-driven documentation types are the ones most sorely missing
from the Tapestry world, and that, in my opinion, is where the focus of the
next documentation effort should be. Why? Because that lack is currently the
single biggest impediment to expanding Tapestry's market share (and vitality
as a product) that we currently face.
I recognize that Christophe's product is in its early stages of development,
but I see substantial promise in his work, and I encourage all of us to give
it a look. He's come a great big long way in a few short months.
--
View this message in context: http://old.nabble.com/documentation-improvements-tp27717462p27745805.html
Sent from the Tapestry - Dev mailing list archive at Nabble.com.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org
Re: documentation improvements
Posted by Christophe Cordenier <ch...@gmail.com>.
Hi,
2010/3/1 Ulrich Stärk <ul...@spielviel.de>
> 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.
>
You're right, it requires a lot of efforts to have a secure installation.
>
> 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
>
For the last two points Wooki's approach is to provided easy writing but
also 'clean' writing for import/export purpose. This is why we have chosen
wymeditor as document editor. Also, we have in mind to provide a REST API to
interoperate with other systems (at least get and put)
BTW my experience of wiki is that when the documentation becomes large, it's
hard to find valuable information and there is a lack of interaction with
readers. IMHO The tool that will be chosen for Tapestry documentation must
have a powerful search engine, a clear and easy way to access and navigate
through the documentation + social features in which i really believe to
make the documentation 'alive'
--
Regards,
Christophe Cordenier.
Developer of wooki @wookicentral.com
Re: documentation improvements
Posted by Ulrich Stärk <ul...@spielviel.de>.
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<us...@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
Re: documentation improvements
Posted by Christophe Cordenier <ch...@gmail.com>.
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 <us...@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
>
>
--
Regards,
Christophe Cordenier.
Developer of wooki @wookicentral.com
Re: documentation improvements
Posted by Sebastian Hennebrueder <us...@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