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 <[email protected]> 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: [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]
