Plone › Documentation Team

Keep documentation for previous versions when updating it to reflect new behaviour and features

22 messages

1 2

Raphael Ritz () Re: Keep documentation for previous versions when updating it to reflect new behaviour and features

Reply Threaded

In reply to this post by JoAnna Springsteen

JoAnna Springsteen wrote:
>> Part of the original reason for this email is that we had a small burp in
>> our process. In Plone 3.3, the way versioning is displayed/implemented is
>> completely different than it is in versions 3.0-3.2.
>
> This is the kind of stuff that the framework team shouldn't be doing.
> tsk tsk. /me wags finger

Point taken ...

> But seriously, as we are more involved with documenting PLIPs, we
> should catch this kind of thing early and point out the ramifications
> of making large changes like this.
>
>> In the process of
>> updating this page in the Plone 3 user's manual, we temporarily lost the
>> page that documented how it worked in the previous versions (it was
>> overwritten).
>
> Would something like working copy support on plone.org help?

Not in this case

>
>
>> The warning here is to make sure to do something like this:
>>
>> Versioning (Plone v3.0 - Plone v3.2)
>> Versioning (Plone v3.3+)
>>
>> [from http://plone.org/documentation/manual/plone-3-user-manual/]
>
> Yeah, this is ugly but it works. Better than having an entirely new
> manual for 3.3.

Yes it's ugly but why is it better than having a new manual
for each new version.

Of course they will be redundant as I would assume that new ones
start out as identical copies of the previous ones. But then you
can add, change and remove whatever you want for the new version
without affecting the one for the previous Plone version.

The example given by Darci is spot on as in fact we need both
variants around. That's also exactly the reason why versioning
or staging doesn't help us here.

But before I get to bold on this I'm of course aware that this
approach becomes tedious with regard to correcting errors and
making new additions that apply to versions prior to the
current one as well. In an ideal world we would start with a
perfect documentation/manual so we probably aren't there just
yet but maybe we are getting close?

Raphael

>
>
>> And not to update the current page without retaining the previous
>> information.
>
> again, working copy support ? other ideas? Personally we should be
> using versioning on our docs anyway. Is this a requirement we've
> talked about for the upcoming PHC changes? Maybe we should add this?
>
> J.
>
> ------------------------------------------------------------------------------
> Stay on top of everything new and different, both inside and
> around Java (TM) technology - register by April 22, and save
> $200 on the JavaOne (SM) conference, June 2-5, 2009, San Francisco.
> 300 plus technical and hands-on sessions. Register today.
> Use priority code J9JMT32. http://p.sf.net/sfu/p

------------------------------------------------------------------------------
Stay on top of everything new and different, both inside and
around Java (TM) technology - register by April 22, and save
$200 on the JavaOne (SM) conference, June 2-5, 2009, San Francisco.
300 plus technical and hands-on sessions. Register today.
Use priority code J9JMT32. http://p.sf.net/sfu/p
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

vedaw () Re: Keep documentation for previous versions when updating it to reflect new behaviour and features

Reply Threaded

FWIW, there will be versioning moving forward. And yes, I think we're
getting close to having solid manuals, which means that if we decide to make
the split for minor versions, we could. We're just not quite there yet, but
we will be soon.

Cheers,

- Veda

On 4/20/09 1:21 AM, "Raphael Ritz" <[hidden email]> wrote:

> JoAnna Springsteen wrote:
>>> Part of the original reason for this email is that we had a small burp in
>>> our process. In Plone 3.3, the way versioning is displayed/implemented is
>>> completely different than it is in versions 3.0-3.2.
>>
>> This is the kind of stuff that the framework team shouldn't be doing.
>> tsk tsk. /me wags finger
>
> Point taken ...
>
>> But seriously, as we are more involved with documenting PLIPs, we
>> should catch this kind of thing early and point out the ramifications
>> of making large changes like this.
>>
>>> In the process of
>>> updating this page in the Plone 3 user's manual, we temporarily lost the
>>> page that documented how it worked in the previous versions (it was
>>> overwritten).
>>
>> Would something like working copy support on plone.org help?
>
> Not in this case
>
>>
>>
>>> The warning here is to make sure to do something like this:
>>>
>>> Versioning (Plone v3.0 - Plone v3.2)
>>> Versioning (Plone v3.3+)
>>>
>>> [from http://plone.org/documentation/manual/plone-3-user-manual/]
>>
>> Yeah, this is ugly but it works. Better than having an entirely new
>> manual for 3.3.
>
> Yes it's ugly but why is it better than having a new manual
> for each new version.
>
> Of course they will be redundant as I would assume that new ones
> start out as identical copies of the previous ones. But then you
> can add, change and remove whatever you want for the new version
> without affecting the one for the previous Plone version.
>
> The example given by Darci is spot on as in fact we need both
> variants around. That's also exactly the reason why versioning
> or staging doesn't help us here.
>
> But before I get to bold on this I'm of course aware that this
> approach becomes tedious with regard to correcting errors and
> making new additions that apply to versions prior to the
> current one as well. In an ideal world we would start with a
> perfect documentation/manual so we probably aren't there just
> yet but maybe we are getting close?
>
> Raphael
>
>
>
>>
>>
>>> And not to update the current page without retaining the previous
>>> information.
>>
>> again, working copy support ? other ideas? Personally we should be
>> using versioning on our docs anyway. Is this a requirement we've
>> talked about for the upcoming PHC changes? Maybe we should add this?
>>
>> J.
>>
>>

----------------------------------------------------------------------------->>
-

>> Stay on top of everything new and different, both inside and
>> around Java (TM) technology - register by April 22, and save
>> $200 on the JavaOne (SM) conference, June 2-5, 2009, San Francisco.
>> 300 plus technical and hands-on sessions. Register today.
>> Use priority code J9JMT32. http://p.sf.net/sfu/p
>
>
> ------------------------------------------------------------------------------
> Stay on top of everything new and different, both inside and
> around Java (TM) technology - register by April 22, and save
> $200 on the JavaOne (SM) conference, June 2-5, 2009, San Francisco.
> 300 plus technical and hands-on sessions. Register today.
> Use priority code J9JMT32. http://p.sf.net/sfu/p
> _______________________________________________
> Plone-docs mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/plone-docs

1 2