You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tapestry.apache.org by Ulrich Stärk <ul...@spielviel.de> on 2010/06/30 14:38:05 UTC
documentation effort: state of affairs
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
Re: documentation effort: state of affairs
Posted by Howard Lewis Ship <hl...@gmail.com>.
See, that just seems like the status quo, which has a proven record of
not being good enough.
On Thu, Jul 1, 2010 at 2:15 AM, Ulrich Stärk <ul...@spielviel.de> wrote:
> +1 for non-confluence approach
>
> I really think our efforts should target the user even if it's a bit harder
> for potential contributors.
>
> On 01.07.2010 10:56, Christophe Cordenier wrote:
>>
>> +1 for Confluence approach
>>
>
> ---------------------------------------------------------------------
> 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
Re: documentation effort: state of affairs
Posted by Inge Solvoll <in...@gmail.com>.
I believe it's extremely important that the documentation system is friendly
to authors. User friendly docs are nice, updated and relevant docs are
better.
On Thu, Jul 1, 2010 at 2:37 PM, Robin Komiwes <ro...@gmail.com>wrote:
> +1 for Confluence with Piero's plugin
>
>
> On Thu, Jul 1, 2010 at 11:15 AM, Ulrich Stärk <ul...@spielviel.de> wrote:
>
> > +1 for non-confluence approach
> >
> > I really think our efforts should target the user even if it's a bit
> harder
> > for potential contributors.
> >
> > On 01.07.2010 10:56, Christophe Cordenier wrote:
> >
> >> +1 for Confluence approach
> >>
> >>
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
> > For additional commands, e-mail: dev-help@tapestry.apache.org
> >
> >
>
Re: documentation effort: state of affairs
Posted by Robin Komiwes <ro...@gmail.com>.
+1 for Confluence with Piero's plugin
On Thu, Jul 1, 2010 at 11:15 AM, Ulrich Stärk <ul...@spielviel.de> wrote:
> +1 for non-confluence approach
>
> I really think our efforts should target the user even if it's a bit harder
> for potential contributors.
>
> On 01.07.2010 10:56, Christophe Cordenier wrote:
>
>> +1 for Confluence approach
>>
>>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
> For additional commands, e-mail: dev-help@tapestry.apache.org
>
>
Re: documentation effort: state of affairs
Posted by Ulrich Stärk <ul...@spielviel.de>.
+1 for non-confluence approach
I really think our efforts should target the user even if it's a bit harder for potential contributors.
On 01.07.2010 10:56, Christophe Cordenier wrote:
> +1 for Confluence approach
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org
Re: documentation effort: state of affairs
Posted by Christophe Cordenier <ch...@gmail.com>.
+1 for Confluence approach
--
Regards,
Christophe Cordenier.
Committer on Apache Tapestry 5
Co-creator of wooki @wookicentral.com
Re: documentation effort: state of affairs
Posted by Howard Lewis Ship <hl...@gmail.com>.
+1 Confluence approach
On Thu, Jul 1, 2010 at 1:49 AM, Ulrich Stärk <ul...@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<hl...@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<ul...@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
Re: documentation effort: state of affairs
Posted by Ulrich Stärk <ul...@spielviel.de>.
Indeed. Very good, I'll grant him access as soon as I know his confluence account name.
On 03.07.2010 18:04, Howard Lewis Ship wrote:
> I believe Robin has already filed his CLA.
>
> On Sat, Jul 3, 2010 at 8:15 AM, Ulrich Stärk<ul...@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<ul...@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<hl...@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<ul...@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
>>
>>
>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org
Re: documentation effort: state of affairs
Posted by Howard Lewis Ship <hl...@gmail.com>.
I believe Robin has already filed his CLA.
On Sat, Jul 3, 2010 at 8:15 AM, Ulrich Stärk <ul...@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<ul...@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<hl...@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<ul...@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
Re: documentation effort: state of affairs
Posted by Ulrich Stärk <ul...@spielviel.de>.
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<ul...@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<hl...@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<ul...@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
Re: documentation effort: state of affairs
Posted by Kalle Korhonen <ka...@gmail.com>.
+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 <ul...@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<hl...@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<ul...@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
Re: documentation effort: state of affairs
Posted by Ulrich Stärk <ul...@spielviel.de>.
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<hl...@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<ul...@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
Re: documentation effort: state of affairs
Posted by Piero Sartini <ps...@sartini-its.com>.
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 <hl...@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 <ul...@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
Re: documentation effort: state of affairs
Posted by Ulrich Stärk <ul...@spielviel.de>.
Unfortunately Confluence doesn't support this. The only thing we could do is create a completely new
space with the contents of the old one. But then we would just mimic the behaviour of SVN with a
tool that isn't made for that purpose.
On 30.06.2010 17:22, Howard Lewis Ship wrote:
> 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<ul...@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
Re: documentation effort: state of affairs
Posted by Howard Lewis Ship <hl...@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 <ul...@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
>
>
--
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