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<[email protected]>
wrote:
On Wed, May 5, 2010 at 8:30 AM, Igor
Drobiazko<[email protected]> 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: [email protected]
For additional commands, e-mail: [email protected]
---------------------------------------------------------------------
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]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
