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

Hi Dylan,

(OOPS, I answered this off-list earlier)

On 2010-05-20, Dylan Jay <[email protected]> wrote:
> Hi alex,
> Not sure if you are over the split between kb docs and manuals. 

Probably not. I get that a "knowledge base" is more volatile…

> Since  
> kb is edited by everyone Its going to be much harder to ensure that  
> versions make sense. It should be used for "edge" type docs and  
> evolving ones like faqs, where as the core docs will be removed from  
> there and consolidated into manals. So I think it only makes sense to  
> version manuals.

Right, I get that. My only counter-point is that from the outside looking
in, I don't care :-). Versioning *everything* is a brute force way
to achieve a URL like /documentation/4.0.x/.

Perhaps I'd adjust the strategy a bit to allow the "released" KB be
edited… or I'd pull the KB completely out of the PHC and version
everything else (perhaps this is close to what you suggest).

> And really a LOT of the documentation is developer related so  
> versioning the developer manual is going to be the single biggest win.  
> Developers are the ones feeling the pain of not knowing if the  
> tecquiues they are reading are up to date or not.

Right. I take this to mean that you and I agree on versioning, but
what gets versioned underneath /documentation is debatable.

>
> Dylan Jay
> Technical solution manager
> PretaWeb 99552830
>
> On 21/05/2010, at 12:27 AM, Alex Clark <[email protected]> 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-admi 
>> n
>>
>>
>> --- 
>> --- 
>> --- 
>> ---------------------------------------------------------------------
>>
>> _______________________________________________
>> Plone-docs mailing list
>> [email protected]
>> https://lists.sourceforge.net/lists/listinfo/plone-docs
>
> ------------------------------------------------------------------------------
>
> _______________________________________________
> Plone-docs mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/plone-docs


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