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

Hi,

I'm not on the doc team, but Alex's idea makes sense to me. It follows 
the same pattern as the Apache docs, so it's not like it's never been 
tried before :-)

my $0.02

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
>


-- 
Larry Pitcher
Catapult Solutions

Web:    www.catapultsolutions.net
Email:  [email protected]
Skype:  larry.pitcher
Phone:  509.849.2660

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