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

On 21/05/2010, at 12:40 PM, Alex Clark wrote:

> Hi Dylan,
>
> (OOPS, I answered this off-list earlier)
>
> On 2010-05-20, Dylan Jay <dylan-Q+/Sk2sTzaxWk0Htik3J/[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/.

I think part of the problem here is that the documentation is  
currently in flux between and old and a new structure, so we can't  
look at it from the outside and make judgements on how it will be once  
this latest change is finished.
Once limi finishes the doc area UI there should be much more emphasis  
on official manuals and the kb area should appear much more like a  
staging area for new forms or ideas in documetnation, e.g. how do I  
get deploy to ec2, or how do I integrate SOAP. When those things  
become "core" then they get moved into the manuals section (which I  
believe should be versioned).
I think Israel and Anna are sort of saying the same thing, that  
version makes sense for "mature" documentation, not for all  
documentation. Hense why the user manual has already been versioned.  
The user manual is mature, the themeing manual isn't. The developer  
manual should be our primary focus to make that mature ASAP. The KB  
will never be mature, it's not meant to be.
Also don't forget that version tags will still exist in the KB. It  
should be clearer than it is now. Maybe for the KB, Israel's traversal  
trick is a good idea.
documentation/kb/3.3/myhowto will look up and see if the documentation/ 
kb/myhowto has the 3.3 version tag and then display it accordingly.

But I don't think that's how manuals should be versioned. The plone  
4.0 developer manual should be carefully edited to ensure it's only  
relevant to 4 and removes old stuff only relevant to 3.3.

my 2c anyway. and of course I'm not doc team either I totally respect  
the hard work being put in by the doc team and I think that we should  
be considering workload as well as making clearer for readers. I think  
there is a compromise possible here.


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

My understanding is that KB == PHC and manuals doesn't really have to  
be PHC.

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

yep.

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


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