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/05/01 15:02:44 UTC
[Vote] Documentation system
We've discussed a lot about how documentation should be managed in the
future. Now lets vote about what to do.
Please note that this vote is about the future documentation system
only, not about reworking the complete homepage.
[ ] keep maven2 documentation as is, no need to change.
[ ] re-organize documentation, but keep maven2 as generator (eg. move
documentation to its own module)
[ ] use textile to generate the documentation (
http://textile.thresholdstate.com )
[ ] make use of confluence (
https://cwiki.apache.org/TAPESTRY/tapestry-home.html )
Piero
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org
Re: [Vote] Documentation system
Posted by Christian Riedel <cr...@googlemail.com>.
As far as I can see, there is on the one side the demand of having the main site (or the whole docs) under version control and offline editable and on the other side a wiki-based solution such as confluence would make doc-bug-fixing very easy and fast... (plus the user-contributions in form of comments / wiki articles, blah, blah, you know the rest).
I just searched for "convert apt into confluence" and I found: http://maven.apache.org/doxia/doxia-tools/doxia-converter/index.html.
What about keeping the main site and/or docs in both systems? Just find a consensus about which is the main tool. For example, the docs are now written entirely in apt. If we export them to confluence on a regular basis (once a month or so), people could at least comment them, post links to wiki articles, blogs, etc., ... Releases could be uploaded into different subdirectories inside confluence and so on. It would just be a matter of organizing.
If some committer thinks that confluence is the better way to write docs, he could convert the work back to apt afterwards...
I think docbook, textile and others are also supported. Everyone writes how he wants to. Patches for the maven-based docs could be contributed by others and later published via export to confluence... (including pdf export for those, who want to read it offline)
So I don't see why there can't be a proper consensus on one clear way to go on with the docs. Everybody can write docs in whatever form he likes to and there are tools out there that can convert into lots of other formats. You all mentioned good points on every possible solution, now lets bring the good parts together!
Writing docs should be as easy as possible and writers shouldn't be constrained too much. :)
Am 05.05.2010 um 23:52 schrieb Thiago H. de Paula Figueiredo:
> On Wed, 05 May 2010 18:22:42 -0300, Sebastian Hennebrueder <us...@laliluna.de> wrote:
>
>> Hello,
>
> Hi!
>
>> IMHO, we should by no means make the main pages being editable for every one.
>
> Nobody is suggesting that. The wiki solution would have two separate parts: the official documentation, written and/or revised by committers, and the community area.
>
> If an online edition solution isn't adopted, I would go for pure XHTML for the documentation itself. I wrote a Tapestry course just using XHTML, CSS (adapting the stylesheet described in http://www.alistapart.com/articles/boom), PrinceXML to generate a PDF and a little bit of XSLT to generate a table of contents, convert to other formats and some other small tasks. I can share an HTML example and my CSS and XSLT files if you want.
>
> --
> Thiago H. de Paula Figueiredo
> Independent Java, Apache Tapestry 5 and Hibernate consultant, developer, and instructor
> Owner, 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
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org
Re: [Vote] Documentation system
Posted by "Thiago H. de Paula Figueiredo" <th...@gmail.com>.
On Wed, 05 May 2010 18:22:42 -0300, Sebastian Hennebrueder
<us...@laliluna.de> wrote:
> Hello,
Hi!
> IMHO, we should by no means make the main pages being editable for every
> one.
Nobody is suggesting that. The wiki solution would have two separate
parts: the official documentation, written and/or revised by committers,
and the community area.
If an online edition solution isn't adopted, I would go for pure XHTML for
the documentation itself. I wrote a Tapestry course just using XHTML, CSS
(adapting the stylesheet described in
http://www.alistapart.com/articles/boom), PrinceXML to generate a PDF and
a little bit of XSLT to generate a table of contents, convert to other
formats and some other small tasks. I can share an HTML example and my CSS
and XSLT files if you want.
--
Thiago H. de Paula Figueiredo
Independent Java, Apache Tapestry 5 and Hibernate consultant, developer,
and instructor
Owner, 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: [Vote] Documentation system
Posted by Sebastian Hennebrueder <us...@laliluna.de>.
Hello,
well there was an exchange of arguments but no decision was taken.
My opinion on this topic is:
The main site is rarely changed and I don't see the need nore the
volunteers to create additional content for the main pages. apart from a
community documentation area like the one we already have.
IMHO, we should by no means make the main pages being editable for every
one. Those changes should be carefully either done or at least reviewed
by commiters. I am not sure, if we can protect special paths inside of
confluence or create workflows.
A static website generator can use a normal version control based
approach to create patches which are finally commited by commiters.
Assumed that we use a static website generator for documentation as
well, then using one for the main page allows a simpler integration of
those two contents. But on the other hand the integration with the
community documentation is harder.
I prefer a static website generator for the main page as I dislike
writing in a Wiki editor because it is sometimes slow, requires being
online and you don't have things like 'search and replace' at your
finger tips.
Considering the documentation, I believe that it is pretty natural to
code and document at the same time and at any place in the world even
being offline. Therefore we should use something static here. I prefer
to migrate from Maven based documentation to a Textile format being put
together with a website generator as the Maven templates are very
complex to adapt and hard to extend and because Textile is a very
efficient approach to write documentation.
What about setting up a new vote with the following items:
main website
- leave technology as is
- migrate to a static website generator as shown by my Proof of concept
- migrate to confluence
documentation
- leave technology as is
- migrate to a static website generator as shown by my Proof of concept
- migrate to confluence
Best Regards
Sebastian
Am 05.05.10 19:55, schrieb Ulrich Stärk:
> This is at least the third time we discuss the pros and cons of using a
> wiki system or some other collaborative tool for documentation and site.
> What came up during the past discussions was that there are good reasons
> for not putting the documentation into some collaborative tool but
> rather keep it in Subversion. I had the impression that the consensus
> was on keeping the documentation under source control and migrate the
> site to Confluence. Am I wrong here?
>
> Uli
>
> On 05.05.2010 19:28, Michael Gerzabek wrote:
>> The other question that came to my mind is: Who is willing to write some
>> docs? What's the use of a "super documentation system" if there is noone
>> out to finally write and update(!) some concise docs - be it tutorials,
>> user guides, or whatever?
>>
>> APT-based in a separate module (tapestry5-docs) via svn is at least as
>> efficient as Wiki-based. You have versioning without extra costs and use
>> your IDE and a build system without any extra efforts. You can take your
>> work whereever you want - plane, countryside, etc - and check in the
>> next time you have svn access. With all the benefits a VCS brings when a
>> plurality of people work on the same piece of work.
>>
>> Furthermore it would occasionally bring new committers into the club ...
>>
>> The thing is you need to oblige to acutally do docs, no matter what
>> technical system is behind the scenes.
>>
>> Michael
>>
>> Am 05.05.2010 18:41, schrieb Kalle Korhonen:
>>> I don't think it needs to be either/or approach. The current APT-based
>>> reference documentation is of good quality, I think most people can
>>> agree with that. The principal issue is people feel the current
>>> documentation needs to be supplemented with more official tutorials
>>> and user guides that, in my opinion, are easier to write with some
>>> Wiki-based system such as Confluence since they generally take lots of
>>> edits and input from multiple people to get it right.
>>>
>>> Kalle
>>>
>>>
>>> On Wed, May 5, 2010 at 12:32 AM, Massimo Lusetti<ml...@gmail.com>
>>> wrote:
>>>> On Wed, May 5, 2010 at 8:30 AM, Igor
>>>> Drobiazko<ig...@gmail.com> wrote:
>>>>
>>>>> I don't like wiki-based documentation because of their proprietary
>>>>> formats.
>>>>> Furthermore you have to be online to access it. I believe we need an
>>>>> appealing home page for basic stuff like introduction, short getting
>>>>> started
>>>>> etc. The user guide / reference should be written in Docbook. Spring
>>>>> and
>>>>> Hibernate guys proved that this is the way to provide a good
>>>>> documentation.
>>>>> The documentation should be downloadable.
>>>> Again today I agree with you.
>>>>
>>>> As I already stated I don't hate apt that much but I don't even write
>>>> Tapestry docs. Having said that using Docbook or Maven APT is
>>>> basically the same and a matter of taste to some degree, I would
>>>> definetly go for a solution where I can have the docs on my offline
>>>> PCs or have a printable copy maybe relative to a stable release.
>>>>
>>>> So from switching to Confluence and stick with Maven apt I'll choose
>>>> the latter.
>>>>
>>>> Cheers
>>>> --
>>>> Massimo
>>>> http://meridio.blogspot.com
>>>>
>>>> ---------------------------------------------------------------------
>>>> 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
>>>
>>
>>
>> ---------------------------------------------------------------------
>> 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: [Vote] Documentation system
Posted by Piero Sartini <li...@pierosartini.de>.
> This is at least the third time we discuss the pros and cons of using a wiki
> system or some other collaborative tool for documentation and site. What
> came up during the past discussions was that there are good reasons for not
> putting the documentation into some collaborative tool but rather keep it in
> Subversion. I had the impression that the consensus was on keeping the
> documentation under source control and migrate the site to Confluence. Am I
> wrong here?
>From my point of view you are correct in that there was a lot of
discussion - but I don't think there was any consensus.
This thread was intended to start a vote and decide how to go on with
the documentation..
But seems it ended up in just another discussion...
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org
Re: [Vote] Documentation system
Posted by Ulrich Stärk <ul...@spielviel.de>.
This is at least the third time we discuss the pros and cons of using a wiki system or some other
collaborative tool for documentation and site. What came up during the past discussions was that
there are good reasons for not putting the documentation into some collaborative tool but rather
keep it in Subversion. I had the impression that the consensus was on keeping the documentation
under source control and migrate the site to Confluence. Am I wrong here?
Uli
On 05.05.2010 19:28, Michael Gerzabek wrote:
> The other question that came to my mind is: Who is willing to write some
> docs? What's the use of a "super documentation system" if there is noone
> out to finally write and update(!) some concise docs - be it tutorials,
> user guides, or whatever?
>
> APT-based in a separate module (tapestry5-docs) via svn is at least as
> efficient as Wiki-based. You have versioning without extra costs and use
> your IDE and a build system without any extra efforts. You can take your
> work whereever you want - plane, countryside, etc - and check in the
> next time you have svn access. With all the benefits a VCS brings when a
> plurality of people work on the same piece of work.
>
> Furthermore it would occasionally bring new committers into the club ...
>
> The thing is you need to oblige to acutally do docs, no matter what
> technical system is behind the scenes.
>
> Michael
>
> Am 05.05.2010 18:41, schrieb Kalle Korhonen:
>> I don't think it needs to be either/or approach. The current APT-based
>> reference documentation is of good quality, I think most people can
>> agree with that. The principal issue is people feel the current
>> documentation needs to be supplemented with more official tutorials
>> and user guides that, in my opinion, are easier to write with some
>> Wiki-based system such as Confluence since they generally take lots of
>> edits and input from multiple people to get it right.
>>
>> Kalle
>>
>>
>> On Wed, May 5, 2010 at 12:32 AM, Massimo Lusetti<ml...@gmail.com>
>> wrote:
>>> On Wed, May 5, 2010 at 8:30 AM, Igor
>>> Drobiazko<ig...@gmail.com> wrote:
>>>
>>>> I don't like wiki-based documentation because of their proprietary
>>>> formats.
>>>> Furthermore you have to be online to access it. I believe we need an
>>>> appealing home page for basic stuff like introduction, short getting
>>>> started
>>>> etc. The user guide / reference should be written in Docbook. Spring
>>>> and
>>>> Hibernate guys proved that this is the way to provide a good
>>>> documentation.
>>>> The documentation should be downloadable.
>>> Again today I agree with you.
>>>
>>> As I already stated I don't hate apt that much but I don't even write
>>> Tapestry docs. Having said that using Docbook or Maven APT is
>>> basically the same and a matter of taste to some degree, I would
>>> definetly go for a solution where I can have the docs on my offline
>>> PCs or have a printable copy maybe relative to a stable release.
>>>
>>> So from switching to Confluence and stick with Maven apt I'll choose
>>> the latter.
>>>
>>> Cheers
>>> --
>>> Massimo
>>> http://meridio.blogspot.com
>>>
>>> ---------------------------------------------------------------------
>>> 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
>>
>
>
> ---------------------------------------------------------------------
> 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: [Vote] Documentation system
Posted by Michael Gerzabek <mi...@gmx.net>.
The other question that came to my mind is: Who is willing to write some
docs? What's the use of a "super documentation system" if there is noone
out to finally write and update(!) some concise docs - be it tutorials,
user guides, or whatever?
APT-based in a separate module (tapestry5-docs) via svn is at least as
efficient as Wiki-based. You have versioning without extra costs and use
your IDE and a build system without any extra efforts. You can take your
work whereever you want - plane, countryside, etc - and check in the
next time you have svn access. With all the benefits a VCS brings when a
plurality of people work on the same piece of work.
Furthermore it would occasionally bring new committers into the club ...
The thing is you need to oblige to acutally do docs, no matter what
technical system is behind the scenes.
Michael
Am 05.05.2010 18:41, schrieb Kalle Korhonen:
> I don't think it needs to be either/or approach. The current APT-based
> reference documentation is of good quality, I think most people can
> agree with that. The principal issue is people feel the current
> documentation needs to be supplemented with more official tutorials
> and user guides that, in my opinion, are easier to write with some
> Wiki-based system such as Confluence since they generally take lots of
> edits and input from multiple people to get it right.
>
> Kalle
>
>
> On Wed, May 5, 2010 at 12:32 AM, Massimo Lusetti<ml...@gmail.com> wrote:
>
>> On Wed, May 5, 2010 at 8:30 AM, Igor Drobiazko<ig...@gmail.com> wrote:
>>
>>
>>> I don't like wiki-based documentation because of their proprietary formats.
>>> Furthermore you have to be online to access it. I believe we need an
>>> appealing home page for basic stuff like introduction, short getting started
>>> etc. The user guide / reference should be written in Docbook. Spring and
>>> Hibernate guys proved that this is the way to provide a good documentation.
>>> The documentation should be downloadable.
>>>
>> Again today I agree with you.
>>
>> As I already stated I don't hate apt that much but I don't even write
>> Tapestry docs. Having said that using Docbook or Maven APT is
>> basically the same and a matter of taste to some degree, I would
>> definetly go for a solution where I can have the docs on my offline
>> PCs or have a printable copy maybe relative to a stable release.
>>
>> So from switching to Confluence and stick with Maven apt I'll choose the latter.
>>
>> Cheers
>> --
>> Massimo
>> http://meridio.blogspot.com
>>
>> ---------------------------------------------------------------------
>> 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
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org
Re: [Vote] Documentation system
Posted by Kalle Korhonen <ka...@gmail.com>.
I don't think it needs to be either/or approach. The current APT-based
reference documentation is of good quality, I think most people can
agree with that. The principal issue is people feel the current
documentation needs to be supplemented with more official tutorials
and user guides that, in my opinion, are easier to write with some
Wiki-based system such as Confluence since they generally take lots of
edits and input from multiple people to get it right.
Kalle
On Wed, May 5, 2010 at 12:32 AM, Massimo Lusetti <ml...@gmail.com> wrote:
> On Wed, May 5, 2010 at 8:30 AM, Igor Drobiazko <ig...@gmail.com> wrote:
>
>> I don't like wiki-based documentation because of their proprietary formats.
>> Furthermore you have to be online to access it. I believe we need an
>> appealing home page for basic stuff like introduction, short getting started
>> etc. The user guide / reference should be written in Docbook. Spring and
>> Hibernate guys proved that this is the way to provide a good documentation.
>> The documentation should be downloadable.
>
> Again today I agree with you.
>
> As I already stated I don't hate apt that much but I don't even write
> Tapestry docs. Having said that using Docbook or Maven APT is
> basically the same and a matter of taste to some degree, I would
> definetly go for a solution where I can have the docs on my offline
> PCs or have a printable copy maybe relative to a stable release.
>
> So from switching to Confluence and stick with Maven apt I'll choose the latter.
>
> Cheers
> --
> Massimo
> http://meridio.blogspot.com
>
> ---------------------------------------------------------------------
> 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: [Vote] Documentation system
Posted by Massimo Lusetti <ml...@gmail.com>.
On Wed, May 5, 2010 at 8:30 AM, Igor Drobiazko <ig...@gmail.com> wrote:
> I don't like wiki-based documentation because of their proprietary formats.
> Furthermore you have to be online to access it. I believe we need an
> appealing home page for basic stuff like introduction, short getting started
> etc. The user guide / reference should be written in Docbook. Spring and
> Hibernate guys proved that this is the way to provide a good documentation.
> The documentation should be downloadable.
Again today I agree with you.
As I already stated I don't hate apt that much but I don't even write
Tapestry docs. Having said that using Docbook or Maven APT is
basically the same and a matter of taste to some degree, I would
definetly go for a solution where I can have the docs on my offline
PCs or have a printable copy maybe relative to a stable release.
So from switching to Confluence and stick with Maven apt I'll choose the latter.
Cheers
--
Massimo
http://meridio.blogspot.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org
Re: [Vote] Documentation system
Posted by Igor Drobiazko <ig...@gmail.com>.
I don't like wiki-based documentation because of their proprietary formats.
Furthermore you have to be online to access it. I believe we need an
appealing home page for basic stuff like introduction, short getting started
etc. The user guide / reference should be written in Docbook. Spring and
Hibernate guys proved that this is the way to provide a good documentation.
The documentation should be downloadable.
On Wed, May 5, 2010 at 12:15 AM, Piero Sartini <li...@pierosartini.de>wrote:
> > Tapestry is so fun to use and develop, imho documentation should be as
> well.
> > I understand and agree with christian arguments, so i guess we should
> vote
> > for confluence for all the good reasons explained, but this should not
> > exclude to work on a fun and appealing front page.
>
> Agreed - but we should try to focus on one topic at a time. An
> appealing front page is a different story from documentation.
> Lets discuss this in another thread..
>
> Piero
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
> For additional commands, e-mail: dev-help@tapestry.apache.org
>
>
--
Best regards,
Igor Drobiazko
http://tapestry5.de/blog
Re: [Vote] Documentation system
Posted by Piero Sartini <li...@pierosartini.de>.
> Tapestry is so fun to use and develop, imho documentation should be as well.
> I understand and agree with christian arguments, so i guess we should vote
> for confluence for all the good reasons explained, but this should not
> exclude to work on a fun and appealing front page.
Agreed - but we should try to focus on one topic at a time. An
appealing front page is a different story from documentation.
Lets discuss this in another thread..
Piero
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org
Re: [Vote] Documentation system
Posted by Christophe Cordenier <ch...@gmail.com>.
Tapestry is so fun to use and develop, imho documentation should be as
well. I understand and agree with christian arguments, so i guess we
should vote for confluence for all the good reasons explained, but
this should not exclude to work on a fun and appealing front page.
Regards
Christophe Cordenier
Envoyé de mon iPhone
Le 4 mai 2010 à 23:06, "Thiago H. de Paula Figueiredo" <thiagohp@gmail.co
m> a écrit :
> On Tue, 04 May 2010 17:26:27 -0300, Christian Riedel <cr.mlist@googlemail.com
> > wrote:
>
>> I'd use confluence because:
>> - documentation can be added on-the-fly
>
> This is very important, IMHO.
>
>> - fixes to older documentation is not dependent on the release of
>> the framework
>> - the infrastructure is already there
>> - more contributers could be allowed access to add documentation
>
> This is very important, IMHO, even having a separate part for
> official documentation. If someone writes a nice wiki page, we could
> easily make it part of the official documentation.
>
>> - comments by users on documentation pages could help you to find
>> errors fast and others to get an alternative solution
>
> I wasn't thinking of it and that's a very nice feature. Thanks
> Christian!
>
>> ...and jira's documentation is quite ok imho:
>> http://confluence.atlassian.com/display/ALLDOC/JIRA+Documentation+Directory
>>
>> negative point is that everybody has to learn that confluence
>> syntax and nobody likes writing documentation anyway...
>
> And also converting the current documentation. This would be a
> problem for any solution besides keep on using the same tools we
> already use (Maven).
>
> +1 to Confluence.
>
> --
> Thiago H. de Paula Figueiredo
> Independent Java, Apache Tapestry 5 and Hibernate consultant,
> developer, and instructor
> Owner, 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
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org
Re: [Vote] Documentation system
Posted by "Thiago H. de Paula Figueiredo" <th...@gmail.com>.
On Tue, 04 May 2010 17:26:27 -0300, Christian Riedel
<cr...@googlemail.com> wrote:
> I'd use confluence because:
> - documentation can be added on-the-fly
This is very important, IMHO.
> - fixes to older documentation is not dependent on the release of the
> framework
> - the infrastructure is already there
> - more contributers could be allowed access to add documentation
This is very important, IMHO, even having a separate part for official
documentation. If someone writes a nice wiki page, we could easily make it
part of the official documentation.
> - comments by users on documentation pages could help you to find errors
> fast and others to get an alternative solution
I wasn't thinking of it and that's a very nice feature. Thanks Christian!
> ...and jira's documentation is quite ok imho:
> http://confluence.atlassian.com/display/ALLDOC/JIRA+Documentation+Directory
>
> negative point is that everybody has to learn that confluence syntax and
> nobody likes writing documentation anyway...
And also converting the current documentation. This would be a problem for
any solution besides keep on using the same tools we already use (Maven).
+1 to Confluence.
--
Thiago H. de Paula Figueiredo
Independent Java, Apache Tapestry 5 and Hibernate consultant, developer,
and instructor
Owner, 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: [Vote] Documentation system
Posted by Howard Lewis Ship <hl...@gmail.com>.
On Tue, May 4, 2010 at 1:26 PM, Christian Riedel
<cr...@googlemail.com> wrote:
> [x] confluence
>
>
> I'd use confluence because:
> - documentation can be added on-the-fly
> - fixes to older documentation is not dependent on the release of the framework
> - the infrastructure is already there
> - more contributers could be allowed access to add documentation
> - comments by users on documentation pages could help you to find errors fast and others to get an alternative solution
>
> ...and jira's documentation is quite ok imho:
> http://confluence.atlassian.com/display/ALLDOC/JIRA+Documentation+Directory
>
> negative point is that everybody has to learn that confluence syntax and nobody likes writing documentation anyway...
>
> Howard, could I convince you a bit to decide for one solution? :)
> If you don't say "that's ok" nothing will move and people are waiting for proper documentation... My points from above have been discussed a lot of times on the list. Do you find another documentation system with the same benefits?
>
I'm swinging towards Confluence, for all the reasons you've mentioned.
>
> Am 04.05.2010 um 18:52 schrieb Howard Lewis Ship:
>
>> I still don't have a strong opinion on this; I'm dissatisfied with
>> what we have now.
>>
>> On Sat, May 1, 2010 at 6:02 AM, Piero Sartini <li...@pierosartini.de> wrote:
>>> We've discussed a lot about how documentation should be managed in the
>>> future. Now lets vote about what to do.
>>> Please note that this vote is about the future documentation system
>>> only, not about reworking the complete homepage.
>>>
>>> [ ] keep maven2 documentation as is, no need to change.
>>> [ ] re-organize documentation, but keep maven2 as generator (eg. move
>>> documentation to its own module)
>>> [ ] use textile to generate the documentation (
>>> http://textile.thresholdstate.com )
>>> [ ] make use of confluence (
>>> https://cwiki.apache.org/TAPESTRY/tapestry-home.html )
>>
>> +1
>>
>> Basically, this is the only option that allows "many hands to make light work".
>>
>>>
>>> Piero
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
>>> For additional commands, e-mail: dev-help@tapestry.apache.org
>>>
>>>
>>
>>
>>
>> --
>> Howard M. Lewis Ship
>>
>> Creator of Apache Tapestry
>>
>> The source for Tapestry training, mentoring and support. Contact me to
>> learn how I can get you up and productive in Tapestry fast!
>>
>> (971) 678-5210
>> http://howardlewisship.com
>>
>> ---------------------------------------------------------------------
>> 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
>
>
--
Howard M. Lewis Ship
Creator of Apache Tapestry
The source for Tapestry training, mentoring and support. Contact me to
learn how I can get you up and productive in Tapestry fast!
(971) 678-5210
http://howardlewisship.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org
Re: [Vote] Documentation system
Posted by Christian Riedel <cr...@googlemail.com>.
[x] confluence
I'd use confluence because:
- documentation can be added on-the-fly
- fixes to older documentation is not dependent on the release of the framework
- the infrastructure is already there
- more contributers could be allowed access to add documentation
- comments by users on documentation pages could help you to find errors fast and others to get an alternative solution
...and jira's documentation is quite ok imho:
http://confluence.atlassian.com/display/ALLDOC/JIRA+Documentation+Directory
negative point is that everybody has to learn that confluence syntax and nobody likes writing documentation anyway...
Howard, could I convince you a bit to decide for one solution? :)
If you don't say "that's ok" nothing will move and people are waiting for proper documentation... My points from above have been discussed a lot of times on the list. Do you find another documentation system with the same benefits?
Am 04.05.2010 um 18:52 schrieb Howard Lewis Ship:
> I still don't have a strong opinion on this; I'm dissatisfied with
> what we have now.
>
> On Sat, May 1, 2010 at 6:02 AM, Piero Sartini <li...@pierosartini.de> wrote:
>> We've discussed a lot about how documentation should be managed in the
>> future. Now lets vote about what to do.
>> Please note that this vote is about the future documentation system
>> only, not about reworking the complete homepage.
>>
>> [ ] keep maven2 documentation as is, no need to change.
>> [ ] re-organize documentation, but keep maven2 as generator (eg. move
>> documentation to its own module)
>> [ ] use textile to generate the documentation (
>> http://textile.thresholdstate.com )
>> [ ] make use of confluence (
>> https://cwiki.apache.org/TAPESTRY/tapestry-home.html )
>
> +1
>
> Basically, this is the only option that allows "many hands to make light work".
>
>>
>> Piero
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
>> For additional commands, e-mail: dev-help@tapestry.apache.org
>>
>>
>
>
>
> --
> Howard M. Lewis Ship
>
> Creator of Apache Tapestry
>
> The source for Tapestry training, mentoring and support. Contact me to
> learn how I can get you up and productive in Tapestry fast!
>
> (971) 678-5210
> http://howardlewisship.com
>
> ---------------------------------------------------------------------
> 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: [Vote] Documentation system
Posted by Howard Lewis Ship <hl...@gmail.com>.
I still don't have a strong opinion on this; I'm dissatisfied with
what we have now.
On Sat, May 1, 2010 at 6:02 AM, Piero Sartini <li...@pierosartini.de> wrote:
> We've discussed a lot about how documentation should be managed in the
> future. Now lets vote about what to do.
> Please note that this vote is about the future documentation system
> only, not about reworking the complete homepage.
>
> [ ] keep maven2 documentation as is, no need to change.
> [ ] re-organize documentation, but keep maven2 as generator (eg. move
> documentation to its own module)
> [ ] use textile to generate the documentation (
> http://textile.thresholdstate.com )
> [ ] make use of confluence (
> https://cwiki.apache.org/TAPESTRY/tapestry-home.html )
+1
Basically, this is the only option that allows "many hands to make light work".
>
> Piero
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
> For additional commands, e-mail: dev-help@tapestry.apache.org
>
>
--
Howard M. Lewis Ship
Creator of Apache Tapestry
The source for Tapestry training, mentoring and support. Contact me to
learn how I can get you up and productive in Tapestry fast!
(971) 678-5210
http://howardlewisship.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org