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

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
something is only valid since Plone X.Y next to that paragraph, and
that's why we are doing for now. A bit more confusing, I must agree,
but more pragmatic too.

That policy could change when we have less docs in the "official/core"
doc section to update. Time and experience will guide us. :-)

-- israel

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