tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ulrich Stärk <...@spielviel.de>
Subject Re: documentation effort: state of affairs
Date Thu, 01 Jul 2010 08:49:07 GMT
I think the choice we have to make is whether we want to make the documentation easy to maintain
and 
set the barrier for potential contributors as low as possible, at the same time making it
a bit 
harder for users to get documentation for their specific version (Confluence approach) or
whether we 
want to give users documentation for their specific version where we can also keep the documentation

for older versions updated, at the same time making it a bit harder for the authors (svn +
some 
documentation build tool).

On 30.06.2010 18:45, Piero Sartini wrote:
> This could work using the "Copy Space Plugin".
> https://studio.plugins.atlassian.com/wiki/display/CPSP/Confluence+Copy+Space+Plugin
>
> We would end up with different spaces:
> TAP5 could be the trunk,
> TAP51, TAP52, etc the snapshots.
>
>             Piero
>
> 2010/6/30 Howard Lewis Ship<hlship@gmail.com>:
>> What about a way to snapshot the current documentation?  So we could
>> snapshot the current state as "5.1", then start updating it. When 5.2
>> goes final we could snapshot that as "5.2".  I.e., tree it a bit like
>> SVN, but inside Confluence.
>>
>> On Wed, Jun 30, 2010 at 5:38 AM, Ulrich Stärk<uli@spielviel.de>  wrote:
>>> This is just to keep you up-to-date to what I'm doing. Ideas and suggestions
>>> are most welcome.
>>>
>>> I've finished porting the 5.1 reference documentation and the cookbok to
>>> confluence. This was a matter of using a doxia converter and some additional
>>> regexps to clean up things. Importing the stuff into confluence had to be
>>> done manually though.
>>>
>>> I'm now investigating how to keep the documentation in sync with our
>>> releases so that people interested in the current documentation, the
>>> documentation for a specific version and people interested in the
>>> differences between two versions all find what they need. My initial idea
>>> was that we could do with some macros that mark parts of the documentation
>>> as deprecated or add a "since" information to it. I fear that this will make
>>> the documentation unreadable though as features are added, changed and
>>> removed. People looking for documentation on a specific version will have to
>>> ignore the parts talking about deprecation or addition of features not
>>> applicable to their version of the product. Or we have to support that by
>>> hiding the unnecessary information by means of javascript or something. All
>>> that is cumbersome to the reader though.
>>>
>>> An easier approach would be to not put the reference documentation into
>>> confluence but maintain it in svn where it would live the same lifecycle as
>>> the product itself. This will make it a bit harder to maintain for the
>>> documentation authors though.
>>>
>>> Right now I am favouring the second approach where we put the reference
>>> documentation (i.e. the user guide) into svn and have tutorials and cookbook
>>> articles in confluence. I will work on that in the next days.
>>>
>>> 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


Mime
View raw message