tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christian Edward Gruber <christianedwardgru...@gmail.com>
Subject Re: [DISCUSS] new documentation organization and versioning
Date Tue, 01 Jun 2010 20:23:47 GMT
I think this is great, but I'd put a snapshot of the docs at the time  
of release somewhere, since some things may change that are confusing  
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ärk <uli@spielviel.de> wrote:

> By chance I had a conversation with someone experienced in  
> organizing documentation for software products later today and he  
> recommends to follow a pragmatic approach. The documentation should  
> always represent the latest development version and features should  
> simply be marked with the version of their introduction. In case of  
> changes to previous behaviour old and new behaviour should be  
> documented, again with a note when the changes were introduced.  
> Everything more complicated like managing a n-version documentation  
> is likely to need a lot of rules and discipline and is therefore  
> likely to not being successful.
>
> This is more or less what I proposed in the last approach except  
> that it isn't coupled to a change in our release process. Do you  
> think this would be feasible?
>
> Uli
>
> On 01.06.2010 12:49, Ulrich Stärk wrote:
>> With the upcoming switch from maven-generated documentation to
>> documentation kept in confluence we should discuss how we will  
>> organize
>> the documentation in the future, especially with respect to  
>> 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  
>> we
>> have several completely independent versions of the documentation  
>> 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  
>> "Tapestry
>> dev" which themselves again contain independent pages for the  
>> 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  
>> 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  
>> (which
>> might take some time) we could begin releasing at a fixed interval,  
>> say
>> every two or three months. That way the current release version and  
>> the
>> current development version wouldn't drift apart that much concerning
>> documentation and possibly long-awaited new features. That way it  
>> 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  
>> 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


Mime
View raw message