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<[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]
--
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]
