tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ulrich Stärk <...@spielviel.de>
Subject Re: [Vote] Documentation system
Date Wed, 05 May 2010 17:55:53 GMT
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<mlusetti@gmail.com>
>> wrote:
>>> On Wed, May 5, 2010 at 8:30 AM, Igor
>>> Drobiazko<igor.drobiazko@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


Mime
View raw message