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 Sat, 03 Jul 2010 16:04:06 GMT
I believe Robin has already filed his CLA.

On Sat, Jul 3, 2010 at 8:15 AM, Ulrich Stärk <uli@spielviel.de> wrote:
> Very well... What needs to be done now then is to move the documentation for
> the various submodules to confluence. Maybe I'll also create a separate
> space for the documentation, that will make it easier to give access to
> contributors that aren't supposed to edit the site itself. I think I'll
> begin with that tomorrow.
>
> Another thing that needs to be done quite soon is incoroporating the new
> logo into the layout and update the layout so that the documentation looks
> nice. Robin, can you work on that? I'd also really appreciate it if you
> could file a CLA, that will help avoid IP and licensing issues and I can
> then grant you access to the new site and documentation so that you can work
> directly on it.
>
> Cheers,
>
> Uli
>
> On 01.07.2010 19:21, Kalle Korhonen wrote:
>>
>> +1 for Confluence approach. Readable guide even with minor
>> inconsistencies between versions is more important to users than the
>> *potential* for version exactness. The great danger is that the
>> version-specific docs still won't be kept up-to-date in which case its
>> worse than the Confluence approach. Javadocs is the ultimate reference
>> documentation for a particular version - no need to duplicate what's
>> in the Javadocs.
>>
>> Kalle
>>
>>
>> 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
>>>
>>>
>>
>> ---------------------------------------------------------------------
>> 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