Mailing-List: contact dev-help@tapestry.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Tapestry development" <dev@tapestry.apache.org>
Received-SPF: pass (athena.apache.org: domain of
 christianedwardgruber@gmail.com designates 209.85.212.52 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=from:to:in-reply-to:x-mailer:subject:references:message-id
         :content-type:content-transfer-encoding:mime-version:date:cc;
        b=C+/73m1vtZO5Azr8rZFmJ/vOz6nuuOmtdW+SNsreMFpb4z7eUXbXArBFf/VKKf3KhG
         2JFWGTMh6ZwIi59ph0hNdMjRRcx6Kd9pj11Uq06mfGV82xdRhIIY+lUS3YJYedWsX2kE
         azqWLuosSE11pTfWJrYF1rsxGdFJEPJ9lXTpQ=
From: Christian Edward Gruber <christianedwardgruber@gmail.com>
To: Tapestry development <dev@tapestry.apache.org>
In-Reply-To: <4C0569ED.5020602@spielviel.de>
Subject: Re: [DISCUSS] new documentation organization and versioning
References: <4C04E5B2.5090307@spielviel.de> <4C0569ED.5020602@spielviel.de>
Message-Id: <B0EA6440-9609-4708-948D-DD3BD0EDABAF@gmail.com>
Content-Type: text/plain;
	charset=utf-8;
	format=flowed;
	delsp=yes
Content-Transfer-Encoding: quoted-printable
Mime-Version: 1.0 (iPhone Mail 7E18)
Date: Tue, 1 Jun 2010 16:23:47 -0400
Cc: Tapestry development <dev@tapestry.apache.org>

I think this is great, but I'd put a snapshot of the docs at the time =20=

of release somewhere, since some things may change that are confusing =20=

if someone's, for instance, fixing a project that uses an older version.

Regards,
Christian
Sent from my iPhone.

On Jun 1, 2010, at 16:13, Ulrich St=C3=A4rk <uli@spielviel.de> wrote:

> By chance I had a conversation with someone experienced in =20
> organizing documentation for software products later today and he =20
> recommends to follow a pragmatic approach. The documentation should =20=

> always represent the latest development version and features should =20=

> simply be marked with the version of their introduction. In case of =20=

> changes to previous behaviour old and new behaviour should be =20
> documented, again with a note when the changes were introduced. =20
> Everything more complicated like managing a n-version documentation =20=

> is likely to need a lot of rules and discipline and is therefore =20
> likely to not being successful.
>
> This is more or less what I proposed in the last approach except =20
> that it isn't coupled to a change in our release process. Do you =20
> think this would be feasible?
>
> Uli
>
> On 01.06.2010 12:49, Ulrich St=C3=A4rk wrote:
>> With the upcoming switch from maven-generated documentation to
>> documentation kept in confluence we should discuss how we will =20
>> organize
>> the documentation in the future, especially with respect to =20
>> versioning.
>>
>> Currently all work on Tapestry is done in trunk with some fixes being
>> backported to the 5.1 tag, including documentation. This means that =20=

>> we
>> have several completely independent versions of the documentation =20
>> that
>> can be generated on request. If we want to keep it that way, we will
>> have to somehow artificially version our documentation pages in
>> confluence. E.g. with a parent page "Documentation" and subpages for
>> each Tapestry version like "Tapestry 5.1", "Tapestry 5.0" and =20
>> "Tapestry
>> dev" which themselves again contain independent pages for the =20
>> different
>> topics like cookbook, user guide, tutorial, etc.
>>
>> Another approach could be that we only have the most current
>> documentation in confluence and whenever a release is published, we
>> export the documentation to html and store it somewhere alongside the
>> release. This would have the advantage that we don't have to manage
>> several versions of the documentation but it would also mean that we
>> can't easily amend the documentation of the released version once =20
>> work
>> on the development version has progressed.
>>
>> A third approach could be a mix of the two where we only have the
>> documentation for the current release and for the current development
>> version in confluence.
>>
>> A yet another, more radical approach could come hand in hand with a
>> change of how we develop and release Tapestry. Instead of working
>> towards a fixed set of functionality and release when it's done =20
>> (which
>> might take some time) we could begin releasing at a fixed interval, =20=

>> say
>> every two or three months. That way the current release version and =20=

>> the
>> current development version wouldn't drift apart that much concerning
>> documentation and possibly long-awaited new features. That way it =20
>> might
>> be enough to just have one version of the documentation and mark
>> features not yet in the release version as such.
>>
>> There are possibly many other possibilities that I didn't think of =20=

>> and
>> I'd like to discuss these. What do you think? Have you any other
>> suggestions how to solve this versioning problem?
>>
>> Cheers,
>>
>> Uli
>>
>> ---------------------------------------------------------------------
>> 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