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

On 19/04/2009, at 7:23 PM, Israel Saeta Pérez wrote:

> On Sun, Apr 19, 2009 at 9:43 AM, Raphael Ritz wrote:
>> When it comes to documentation I would not purposefully remove
>> the old stuff per default but simply mark it as such, e.g., like
>> Dylan suggested. I don't see any harm in keeping old documentation
>> around as long as we do it in such a way that people don't get
>> confused.
>
> I definitely agree with keeping documentation for older versions.
>
>> So for me, the question boils down to: how to best avoid potential
>> confusion without simply removing the old stuff?
>
> The "applies to" (archetypes) field of the PHC content-types is
> exactly for that. Some time ago somebody removed the Plone 3.x choices
> for this field and left only Plone 2.5, Plone 3.3. The good part is
> that this frees us from having to bump the "applies to" field of every
> doc that doesn't need changes for the upcoming version, but on the
> other hand it bans us from fine-specifying the version like in the
> docs only valid for 3.3.
>
> I'd prefer to keep it as is now, since the aren't so many changes
> between some version of Plone 3 and the following one, and having to
> "duplicate" all docs when only a paragraph is added to some docs isn't
> very efficient IMO. A more pragmatic approach is specifying that

I'm happy to write the scripts needed that would, before each new  
plone release copy all "official" manuals from the 3.3 folder to a new  
3.4 folder for instance. In addition a "current" folder could alias  
the latest version.

I can see where you are coming from that logically, duplicating  
content seems somehow cludgy but think about it this way.

If there was a need to delete documentation no longer relevant to 3.4  
for instance, you could do that in the 3.4 version without any concern  
for affecting readings using older versions. It will make editing  
easier.

As manuals get larger as the users manual and the theming manual are,  
the "applies to" field becomes meaningless and the documentation is  
going to become confusing to read with "if you're using 3.4 do this...  
if you're using 3.3 do this..."

I personally find it very frustrating to do a search for documentation  
only to find what I'm reading doesn't apply the version I'm using.  A  
version number in the url and browser title and headings is going to  
more quickly spotted than teh "applies to" subheading. Finding your  
version in amounts a long list of numbers is also harder than  
installing Plone 3.4 and seeing 3.4 in the title and knowing you're  
reading the best docs.

Version numbers in the url also mean you will know if the  
documentation applies to your version BEFORE you click on it from  
google or plone search.

If you're worried about diskspace... is that really an issue?

If you're worried about maintaining different versions and doing the  
same edits multiple times... I don't think there is a need to. Once a  
version is old don't update it.

Tell me if I'm being an idiot but I'm failing to see any downside  
other than "it's not how we do it now". Clarity for our readers is  
paramount right?

I also really don't want cause an upset so if you guys don't like idea  
and none of the above convinces you then I'll drop the idea.

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