Re: Proposal to create multiple PHCs inside a top level /documenation folder

Hi Larry,

On 2010-05-21, Larry Pitcher <[email protected]> wrote:
> Hi,
>
> I'm not on the doc team, but Alex's idea makes sense to me. 

I think at least a half a dozen folks on this list have expressed interest 
in some sort of versioning in response to my two proposals. That's why I am 
declaring the doc teams failure to address it as "stop energy" 
and I am moving on ;-)

I don't blame them, I mean I get the reason (sort of). But I think *something* 
could be done to address the concern rather than complete inflexibily,
and unwillingness to do anything but declare that they will do nothing.

Correct me if I am wrong guys, but the only counter-suggestion I have received
from the doc team (Israel and Anne and SteveM AFAICT?) is to be good and start 
closing doc tickets. :-p

And, I (seriously) plan to start doing that, ASAP. But I was hoping to address
some macro-issues first…

(Well, there was also the "traversal hack" suggestion, to be fair. Which I guess
 I am not opposed to, but I don't see it working in a way that would satisfy 
 "versioning". I could be wrong.)

> It follows 
> the same pattern as the Apache docs, so it's not like it's never been 
> tried before :-)

True. It makes sense for a variety of reasons. :-)

> my $0.02

I appreciate your feedback! And all of this is just my 0.02 cents… I'm not
really on the doc team either (although I like to dabble).

>
> Larry Pitcher
>
> On 5/20/2010 7:27 AM, Alex Clark wrote:
>> Hi,
>>
>> Here is a re-print of the last section of my last email to the "longest doc team thread of all time".
>>
>> That thread has gotten a bit unwieldy, so I'd like to start a new convo based on the idea that
>> we can create multiple PHCs inside a top level /documentation folder, to try to make
>> everyone happy.
>>
>> (I would also like to trick Martin into reading this thread again ;-))
>>
>> This has several distinct advantages as far as I can tell:
>>
>> Gives immediacy
>> ===============
>> It creates a sense of immediacy for what (at least I, maybe others) perceive as
>> a "stalled" project (or at least struggling project).
>>
>> By immediacy, I mean that as soon as a 3.3.5 "tag" and and 3.3.6 and 4.0 branch
>> are created, Israel, Anne, et al can continue to work in either 3.3.6 or 4.0,
>> depending what they are working on (i.e. Plone 3 docs, or Plone 4 docs).
>>
>> Ends confusion
>> ==============
>> It completely eliminates the "what does this apply to?" problem. If something
>> Plone 3 specific is found to be in a Plone 4 folder, we delete (or privatize) it
>> because we know the same item exists in the Plone 3 folder, where it should be
>> (or you clean it up for Plone 4, and leave the Plone 3 doc alone).
>>
>> Lets things die
>> ===============
>> When 3.x.x and 4.x.x docs get too old (i.e. when it they are no longer supported
>> by the community) we can privatize the folder. We have no way to kill things
>> other than go through doc by doc and unmark something as 2.5 compatible, AFAICT.
>>
>> Anyway, here it is:
>>
>> ---
>>
>> 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?
>>
>> ---
>>
>> One last thing, if it is starting to feel like X.X.X is too may revisions of docs
>> (which it was to me just now) consider this:
>>
>>      http://plone.org/documentation/release/2.5.x/kb/plone-with-apache/
>>      http://plone.org/documentation/release/3.3.x/kb/plone-with-apache/
>>
>> This would not work, because if a giant mistake is found in 3.3.5/kb/plone-with-apache,
>> it does not give the doc team any sane way to release newer 3.x docs (i.e. 3.3.6)
>> because the next release in that scenario is 4.0.x. (Unless there were a 3.4)
>>
>> Another *last* thing. I'd be willing to stage this somewhere if people would be willing
>> to take a swipe at it. We could even invite the entire community to participate, given
>> that the results could be thrown away if the experiment did not go well.
>>
>> 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