You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tapestry.apache.org by Ulrich Stärk <ul...@spielviel.de> on 2010/06/01 12:49:22 UTC
[DISCUSS] new documentation organization and versioning
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
Re: [DISCUSS] new documentation organization and versioning
Posted by Ulrich Stärk <ul...@spielviel.de>.
That would be possible with user macros, e.g. something like {addedin:5.1.0.8}paragraph
text{addedin} that would expand into some nice markup.
Uli
On 02.06.2010 17:18, Howard Lewis Ship wrote:
> It would be nice if there was an easy way to mark a paragraph of wiki
> text as "Removed in 5.2", "Added in 5.3", etc. Something that would
> put a visible marker into, say, the right hand gutter of the page,
> next to the marked paragraph.
>
> On Wed, Jun 2, 2010 at 12:50 AM, Ulrich Stärk<ul...@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-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
>>
>>
>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org
Re: [DISCUSS] new documentation organization and versioning
Posted by Howard Lewis Ship <hl...@gmail.com>.
It would be nice if there was an easy way to mark a paragraph of wiki
text as "Removed in 5.2", "Added in 5.3", etc. Something that would
put a visible marker into, say, the right hand gutter of the page,
next to the marked paragraph.
On Wed, Jun 2, 2010 at 12:50 AM, Ulrich Stärk <ul...@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-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
>
>
--
Howard M. Lewis Ship
Creator of Apache Tapestry
The source for Tapestry training, mentoring and support. Contact me to
learn how I can get you up and productive in Tapestry fast!
(971) 678-5210
http://howardlewisship.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org
Re: [DISCUSS] new documentation organization and versioning
Posted by Josh Canfield <jo...@gmail.com>.
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 <ul...@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-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
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org
Re: [DISCUSS] new documentation organization and versioning
Posted by Ulrich Stärk <ul...@spielviel.de>.
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-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
Re: [DISCUSS] new documentation organization and versioning
Posted by Robert Zeigler <ro...@scazdl.org>.
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 last 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-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
Re: [DISCUSS] new documentation organization and versioning
Posted by Christian Edward Gruber <ch...@gmail.com>.
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 <ul...@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
Re: [DISCUSS] new documentation organization and versioning
Posted by Ulrich Stärk <ul...@spielviel.de>.
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
Re: [DISCUSS] new documentation organization and versioning
Posted by Dmitry Gusev <dm...@gmail.com>.
On Tue, Jun 1, 2010 at 23:52, Andreas Andreou <an...@di.uoa.gr> wrote:
> Sometimes ppl are forced to use a specific subversion - it makes a lot of
> sense
> if the documentation for that version is still available to them (+ i dont
> see what we lose by keeping older documentation available)
>
I can see one thing we lose - it would be very hard to support several
versions of documentation in wiki.
>
> On Tue, Jun 1, 2010 at 22:13, Dmitry Gusev <dm...@gmail.com> wrote:
> >> I don't think having separate documentation for T5.0, T5.1 and other
> T5.x
> >> is not a good idea.
> >>
> >
> > Sorry, actually what I was trying to say is _I don't think its a good
> > idea_... its definitely bad :)
> >
> > On Tue, Jun 1, 2010 at 23:11, Dmitry Gusev <dm...@gmail.com>
> wrote:
> >
> >> I don't think having separate documentation for T5.0, T5.1 and other
> T5.x
> >> is not a good idea.
> >> I think it is reasonable to have separate documentation for versions
> having
> >> different major number (T3, T4, T5 etc.) but not for version that differ
> in
> >> minor version numbers.
> >> Why one would use earlier version of T5.0 instead of T5.1 if T5.1 is
> >> already released? Its okay if one will see feature that is still in
> >> development (say in trunk) while reading documentation of stable
> release.
> >> This will give him a reason to upgrade after release if he really wants
> this
> >> feature, or plan its work according to direction of ongoing tapestry
> >> development.
> >> So my point is keep all minor version updates together and only make new
> >> separate version of documentation when T6 release will be planned.
> >>
> >>
> >> On Tue, Jun 1, 2010 at 14:49, Ulrich Stärk <ul...@spielviel.de> 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
> >>>
> >>>
> >>
> >>
> >> --
> >> Dmitry Gusev
> >>
> >> AnjLab Team
> >> http://anjlab.com
> >>
> >
> >
> >
> > --
> > Dmitry Gusev
> >
> > AnjLab Team
> > http://anjlab.com
> >
>
>
>
> --
> Andreas Andreou - andyhot@apache.org - http://blog.andyhot.gr
> Tapestry PMC / Tacos developer
> Open Source / JEE Consulting
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
> For additional commands, e-mail: dev-help@tapestry.apache.org
>
>
--
Dmitry Gusev
AnjLab Team
http://anjlab.com
Re: [DISCUSS] new documentation organization and versioning
Posted by Andreas Andreou <an...@di.uoa.gr>.
Sometimes ppl are forced to use a specific subversion - it makes a lot of sense
if the documentation for that version is still available to them (+ i dont
see what we lose by keeping older documentation available)
On Tue, Jun 1, 2010 at 22:13, Dmitry Gusev <dm...@gmail.com> wrote:
>> I don't think having separate documentation for T5.0, T5.1 and other T5.x
>> is not a good idea.
>>
>
> Sorry, actually what I was trying to say is _I don't think its a good
> idea_... its definitely bad :)
>
> On Tue, Jun 1, 2010 at 23:11, Dmitry Gusev <dm...@gmail.com> wrote:
>
>> I don't think having separate documentation for T5.0, T5.1 and other T5.x
>> is not a good idea.
>> I think it is reasonable to have separate documentation for versions having
>> different major number (T3, T4, T5 etc.) but not for version that differ in
>> minor version numbers.
>> Why one would use earlier version of T5.0 instead of T5.1 if T5.1 is
>> already released? Its okay if one will see feature that is still in
>> development (say in trunk) while reading documentation of stable release.
>> This will give him a reason to upgrade after release if he really wants this
>> feature, or plan its work according to direction of ongoing tapestry
>> development.
>> So my point is keep all minor version updates together and only make new
>> separate version of documentation when T6 release will be planned.
>>
>>
>> On Tue, Jun 1, 2010 at 14:49, Ulrich Stärk <ul...@spielviel.de> 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
>>>
>>>
>>
>>
>> --
>> Dmitry Gusev
>>
>> AnjLab Team
>> http://anjlab.com
>>
>
>
>
> --
> Dmitry Gusev
>
> AnjLab Team
> http://anjlab.com
>
--
Andreas Andreou - andyhot@apache.org - http://blog.andyhot.gr
Tapestry PMC / Tacos developer
Open Source / JEE Consulting
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org
Re: [DISCUSS] new documentation organization and versioning
Posted by Dmitry Gusev <dm...@gmail.com>.
> I don't think having separate documentation for T5.0, T5.1 and other T5.x
> is not a good idea.
>
Sorry, actually what I was trying to say is _I don't think its a good
idea_... its definitely bad :)
On Tue, Jun 1, 2010 at 23:11, Dmitry Gusev <dm...@gmail.com> wrote:
> I don't think having separate documentation for T5.0, T5.1 and other T5.x
> is not a good idea.
> I think it is reasonable to have separate documentation for versions having
> different major number (T3, T4, T5 etc.) but not for version that differ in
> minor version numbers.
> Why one would use earlier version of T5.0 instead of T5.1 if T5.1 is
> already released? Its okay if one will see feature that is still in
> development (say in trunk) while reading documentation of stable release.
> This will give him a reason to upgrade after release if he really wants this
> feature, or plan its work according to direction of ongoing tapestry
> development.
> So my point is keep all minor version updates together and only make new
> separate version of documentation when T6 release will be planned.
>
>
> On Tue, Jun 1, 2010 at 14:49, Ulrich Stärk <ul...@spielviel.de> 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
>>
>>
>
>
> --
> Dmitry Gusev
>
> AnjLab Team
> http://anjlab.com
>
--
Dmitry Gusev
AnjLab Team
http://anjlab.com
Re: [DISCUSS] new documentation organization and versioning
Posted by Dmitry Gusev <dm...@gmail.com>.
I don't think having separate documentation for T5.0, T5.1 and other T5.x is
not a good idea.
I think it is reasonable to have separate documentation for versions having
different major number (T3, T4, T5 etc.) but not for version that differ in
minor version numbers.
Why one would use earlier version of T5.0 instead of T5.1 if T5.1 is already
released? Its okay if one will see feature that is still in development (say
in trunk) while reading documentation of stable release. This will give him
a reason to upgrade after release if he really wants this feature, or plan
its work according to direction of ongoing tapestry development.
So my point is keep all minor version updates together and only make new
separate version of documentation when T6 release will be planned.
On Tue, Jun 1, 2010 at 14:49, Ulrich Stärk <ul...@spielviel.de> 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
>
>
--
Dmitry Gusev
AnjLab Team
http://anjlab.com
Re: [DISCUSS] new documentation organization and versioning
Posted by Ulrich Stärk <ul...@spielviel.de>.
Remember that this discussion should center around documentation.
On 01.06.2010 13:58, Christian Edward Gruber wrote:
> +1 to a fixed release cycle. Time boxes are, in my experience, superior
> to feature-boxes in terms of resulting delivery, quality, etc.
>
> Christian.
>
> On Jun 1, 2010, at 7:32 AM, Ulrich Stärk wrote:
>
>> Don't get too excited about it yet. These are just vague ideas...
>>
>> On 01.06.2010 13:12, Inge Solvoll wrote:
>>> Loving the 2-3 months release cycle idea :)
>>>
>>> I suppose it would mean some major changes in how you guys do your
>>> work, but
>>> it would be a huge win to see more of those minor enhancements more
>>> often.
>>> Right now I'm very ready for a 5.2 release, as our team don't want
>>> non-release dependencies. I don't care about major new features, I
>>> just want
>>> the "pageInit" event :)
>>>
>>> On Tue, Jun 1, 2010 at 12:49 PM, Ulrich Stärk<ul...@spielviel.de> 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
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org
Re: [DISCUSS] new documentation organization and versioning
Posted by Christian Edward Gruber <ch...@gmail.com>.
+1 to a fixed release cycle. Time boxes are, in my experience,
superior to feature-boxes in terms of resulting delivery, quality, etc.
Christian.
On Jun 1, 2010, at 7:32 AM, Ulrich Stärk wrote:
> Don't get too excited about it yet. These are just vague ideas...
>
> On 01.06.2010 13:12, Inge Solvoll wrote:
>> Loving the 2-3 months release cycle idea :)
>>
>> I suppose it would mean some major changes in how you guys do your
>> work, but
>> it would be a huge win to see more of those minor enhancements more
>> often.
>> Right now I'm very ready for a 5.2 release, as our team don't want
>> non-release dependencies. I don't care about major new features, I
>> just want
>> the "pageInit" event :)
>>
>> On Tue, Jun 1, 2010 at 12:49 PM, Ulrich Stärk<ul...@spielviel.de>
>> 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
Re: [DISCUSS] new documentation organization and versioning
Posted by Ulrich Stärk <ul...@spielviel.de>.
Don't get too excited about it yet. These are just vague ideas...
On 01.06.2010 13:12, Inge Solvoll wrote:
> Loving the 2-3 months release cycle idea :)
>
> I suppose it would mean some major changes in how you guys do your work, but
> it would be a huge win to see more of those minor enhancements more often.
> Right now I'm very ready for a 5.2 release, as our team don't want
> non-release dependencies. I don't care about major new features, I just want
> the "pageInit" event :)
>
> On Tue, Jun 1, 2010 at 12:49 PM, Ulrich Stärk<ul...@spielviel.de> 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
Re: [DISCUSS] new documentation organization and versioning
Posted by Inge Solvoll <in...@gmail.com>.
Loving the 2-3 months release cycle idea :)
I suppose it would mean some major changes in how you guys do your work, but
it would be a huge win to see more of those minor enhancements more often.
Right now I'm very ready for a 5.2 release, as our team don't want
non-release dependencies. I don't care about major new features, I just want
the "pageInit" event :)
On Tue, Jun 1, 2010 at 12:49 PM, Ulrich Stärk <ul...@spielviel.de> 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
>
>