It's hard to keep up with tapestry versions in all cases. I have
projects still deployed using 5.0.14, as well as 5.1.0.5. Upgrading
isn't always an option even if it's mostly painless.
That said, I generally refer to the javadoc, tapestry source to figure
stuff out. The website documentation has been a good place to get a
story about subject areas. If the javadoc is robust then keeping old
versions of the web docs around is less of a requirment in my mind.
Better package level documentation, putting component parameters and
simple examples in the javadoc, perhaps just cut and paste from the
web docs...
-- Josh
On Jun 2, 2010, at 12:50 AM, Ulrich Stärk <u...@spielviel.de> wrote:
Managing a version of the documentation for each release in
confluence is to the contrary quiet cumbersome. With every new
release we need to *manually* copy the existing documentation to a
new place. Page by page. Unfortunately there is no easy way to just
create a copy of a page and all its subpages at once. All we could
do is export the whole space and import it as a new one. This would
mean one space for each version of the documentation and this will
make administering the whole thing very complex. In addition it
means that fixes to the documentation will have to be done in
multiple places if we want to keep the docs for a released version
up-to-date as well. I fear that nobody is willing to go through that
hassle meaning that the documentation will be that as of the time of
release. Then there is no reason to keep multiple versions, a static
export from the time of release would be enough.
Uli
On 01.06.2010 22:54, Robert Zeigler wrote:
Other than having a branch (or separate diredtory) for 5.0 vs. 5.1
vs. 5.2, I don't see the approach of having separate documentation
for each sub-release as being taxing. Quite the opposite: it seems
to be that being sure to document when a feature was introduced,
removed (String service id injection, eg.), or changed
(ClassTransformation) within the documentation, including keeping
notes of what applies to which version, within the same document is
only going to lead to confusion, and more rules about
documentation. I like having the separate documentation versions.
I'm in the middle of upgrading an app right now from 5.0.14 (yup,
that old) to 5.1.0.5; it was 5.0.14 for a long time because: a) we
had monkey patched/worked around various issues fixed in later T5
releases so there was no pressing need to upgrade and b) the time
commitment to upgrade, test, etc. the application was outweighed by
the need to fix bugs and add features requested by the client.
During the l
ast year+, being able to refer to documentation that is specific to
5.0 was a real boon. So, -1 for single documentation for all
versions. :)
Robert
On Jun 1, 2010, at 6/13:13 PM , Ulrich Stärk 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-unsubscr...@tapestry.apache.org
For additional commands, e-mail: dev-h...@tapestry.apache.org
---
------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tapestry.apache.org
For additional commands, e-mail: dev-h...@tapestry.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tapestry.apache.org
For additional commands, e-mail: dev-h...@tapestry.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tapestry.apache.org
For additional commands, e-mail: dev-h...@tapestry.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tapestry.apache.org
For additional commands, e-mail: dev-h...@tapestry.apache.org
