Re: Proposal to manage documentation similar to (or along with) core software.

On 2010-05-20, Dylan Jay <[email protected]> wrote:
> You continually update plone4 manual until plone5 is nearing release  
> at which time you copy plone4 and start working on plone5.

Hmmm, I suppose you could do that. But I wouldn't do that ;-) If for no other
reason then it is confusing (to me at least) and perhaps leads to demoralization (IMO).

"Continually update plone4 manual until plone 5 is nearing release" reads to me like

"Spend a lot of time in limbo, and make people have to guess which version of Plone the 
 documentation refers to"

I say that based on the fact that Plone 3.0 is a lot different than 3.3.5, but maybe
I am exaggerating.

Anyway, I should also point out that you are talking about manuals and I am talking
about PHCs (as of right now).

Having beat the versioning drum to death, I would like to propose that the doc team let
the "website team" split the documentation as suggested (effectively resulting in 
various branches and at least one tag).

I am starting to feel like that satisfies the most number of folks and has
the least number of drawbacks:

- current /documentation can be "frozen" in /documentation/release/3.3.5
- Israel, Anne, et al can work in /documentation/develop/3.3.6
- Israel, Anne, et al can work in /documentation/develop/4.0
- Israel, Anne, et al can work in /documentation/develop/5.0

If anyone cares, we can go backwards and create a /documentation/release/2.5.5
that is a copy of 3.3.5, with all the content not marked 3 deleted.

Thoughts?

The one drawback I can think of is that if I search for "apache" i might get 
an "old" copy of the content. But if that content is in:

    http://plone.org/documentation/release/2.5.5/kb/plone-with-apache/

or

    http://plone.org/documentation/release/3.3.5/kb/plone-with-apache/

I imagine folks could just "figure it out" ;-) I also imagine that it would be 
easy (i.e. even something I could program ;-)) to add something to PHC that would 
allow it to know what the current release is (similar to PSC).

And if a URL like:

    http://plone.org/documentation/release/3.3.5/kb/plone-with-apache/

was published and 3.3.5 did not match PHC's idea of the current release, the
template could insert an  "info box" that said:

   ================================================================================ 
   |Info (i)                                                                      |
   |Are you sure you were not looking for:                                        |
   |http://plone.org/documentation/release/4.0/kb/plone-with-apache/ ?            |
   ================================================================================ 

Any takers? :-D

(And thank you all for continuing to listen!)

Alex

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


-- 
Alex Clark · http://aclark.net
Author of Plone 3.3 Site Administration · http://aclark.net/plone-site-admin


------------------------------------------------------------------------------

_______________________________________________
Plone-docs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/plone-docs