tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ulrich Stärk <...@spielviel.de>
Subject Re: [DISCUSS] new documentation organization and versioning
Date Wed, 02 Jun 2010 17:31:32 GMT
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<uli@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


Mime
View raw message