tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Howard Lewis Ship <hls...@gmail.com>
Subject Re: documentation effort: state of affairs
Date Thu, 01 Jul 2010 16:27:14 GMT
+1 Confluence approach

On Thu, Jul 1, 2010 at 1:49 AM, Ulrich Stärk <uli@spielviel.de> wrote:
> 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
>
>



-- 
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


Mime
View raw message