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

On 10/05/2010, at 4:58 PM, Israel Saeta Pérez wrote:

> On 05/09/2010 07:55 PM, Alex Clark wrote:
>> Hi, sorry meant to reply to this earlier…
>>
>> On 2010-04-21, Dylan Jay<dylan-Q+/Sk2sTzaxWk0Htik3J/[email protected]>  wrote:
>>
>> …
>>
>>> We just need a nicer folder structure.
>>>
>>> Instead of
>>>
>>> http://plone.org/documentation/manual/plone-3-user-manual
>>>
>>> we could use
>>>
>>> http://plone.org/documentation/manual/3.x/user-manual
>>>
>>> and we could have a redirection to the latest e.g.
>>>
>>> http://plone.org/documentation/manual/latest/user-manual
>>>
>>> This would also mean we have 3 different versions of the manual  
>>> page.
>>> Instead of
>>>
>>> http://plone.org/documentation/manual/
>>>
>>> we would have
>>>
>>> http://plone.org/documentation/manual/2.5
>>> http://plone.org/documentation/manual/3.x
>>> http://plone.org/documentation/manual/4.x
>>>
>>>
>>> KB just works like the existing PHC docs, except that anyone can  
>>> go in
>>> and update the "versions" covered by a doc if a new plone version is
>>> released and the documentation is still relevant to the new version.
>
> Yes, but remember that the KB is based PHC too.
>
>> +1000. Let's make it happen… I will probably have some time this  
>> month.
>>
>> Of course, it'd be nice to get some other folks chiming in to agree
>> or disagree ;-)
>
> Can't we use collections here? We already have the version metadata in
> the manuals.


hmm. sorry I think I my proposal was more confusing that it could be.

I'm proposing two separate ways of dealing with versioning for the KB  
and the manuals.

KB: Keep it the same, ie the way PHC does it. Each content type is  
marked with the versions it applies to. But do allow anyone with edit  
access to updating those versions so that the community can take  
responsibility for saying a howto still applies to plone version 4 for  
instance.

Manuals: Create separate copies of every manual on each major plone  
release.
For example, we move all the current manuals into a folder at

http://plone.org/documentation/manual/plone3

and at the time of the plone4 release we create a new folder at

http://plone.org/documentation/manual/plone4

and start editing those manuals independently from all the older  
plone3 versions.

Pros
------
- Users always know they are reading up to date documentation
- It's very clear what to do when you want to documentation on and  
older version
- The manuals will be simpler as we can simply remove things no longer  
relevant to older releases and we won't have to explain that certain  
things only apply to x release.

Cons
------
- More work if there is a correction needed in more than one major  
release. I suspect this doesn't happen often and I think it's ok to  
let old manuals go unfixed in many cases. We can't do everything. Also  
if we go with the sphnix developer manual then backporting  
documentation fixes to multiple branches is actually manageable using  
svn.






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