tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sebastian Hennebrueder <use...@laliluna.de>
Subject Re: documentation improvements
Date Sun, 28 Feb 2010 20:07:08 GMT
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 <uli@spielviel.de> 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 <uli@spielviel.de> 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: 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