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_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
