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 Sat, 03 Jul 2010 15:15:13 GMT
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


Mime
View raw message