I appreciate the discussion and your opinion. !!
I think we all agree that we will stop binding the documentation on
tapestry.apache.org to the release cycle. But this has no relevance
considering the chosen technology. Both approaches will do
Uli pointed out that he might consider to version the generated output.
This is possible with both approaches.
Deploying new documentation should be a fast process. I believe this can
be achieved with both versions.
Having documentation in git it is a 'git push' on the command line.
Confluence will have a button for this.
I think that the main questions are:
a) How do we prefer to write documentation?
b) How do we open documentation to non core committers?
c) How do the people who write most of the
documentation can write it in the most efficient way?
Considering a) I named a number of reasons why I prefer a normal editor.
Piero pointed out that textile may be another thing to learn. Textile is
not a complex but very natural Wiki language. I wouldn't expect that it
takes more than a couple of minutes to learn Textile. It is natural. A
break is a break and an empty line is a paragraph.
Here is a sample:
h1. bla bla
h2. subsection
a text
more text on a new line
and the next text in a new paragraph
# first
# and then
# and finally
Using pygments to hightlight allows to paste any HTML, XML or Java code
into the textile file. We only need to surround it with:
{% highlight xml|html|java %}
{% endhighlight %}
I found working online cumbersome when writing a lot. I have more than
100 articles on my website and wouldn't come up with the idea to write
them online.
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.
Best Regards
Sebastian
Howard Lewis Ship schrieb:
I think we're in the middle there, where the documentation at
http://tapestry.apache.org/ would no longer be a launch pad to the
releases (4.1, 5.0, 5.1, etc.) but would instead by "latest
documentation" from a recent version of trunk. It would be updated
out-of-release cycle, but would contain links to more stable
documentation, generated for final releases.
In other words, when updating documentation it would appear at
tapestry.formos.com that night, and could appear at
tapestry.apache.org on demand.
On Sun, Feb 28, 2010 at 1:37 AM, Ulrich Stärk <[email protected]> wrote:
Why can't we do that with the generated content? I have to admit that that
point might be a bit more time-consuming, but I believe that having an
up-to-date documentation uncoupled from the release cycle is more benefitial
than spending some extra time when doing a release. In the end releases are
cut every 3 to 6 months. Do we really want to wait that long for a
documentation improvement to be published?
Uli
Howard Lewis Ship schrieb:
One advantage to generating the documentation (not using Confluence)
is the ability to create a static, stand-alone snapshot that we could
make available along with the source and binary distributions.
On Sat, Feb 27, 2010 at 4:22 AM, Ulrich Stärk <[email protected]> wrote:
Apart from that we can also put the exported content under version
control.
Uli
Piero Sartini schrieb:
I really like having everything under version control!
Confluence is doing a great job with its version control. Of course
it's no hg, git or subversion - but versioning their content and
visualize the changes is one of the main functionalities of wikis.
Piero
---------------------------------------------------------------------
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]
