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

On 21/04/2010, at 11:00 AM, Alex Clark wrote:

> On 2010-04-19, Israel Saeta Pérez <[email protected]> wrote:
>> Hello there,
>> We just need a clean UI to make sure people understand that they can
>> edit and create docs in the KB freely. Limi is working on this.
>
> Don't get me wrong, I think the KB is great. And if PHC is a good  
> tool to use to
> create a KB, even better. What I am trying to get people to move  
> towards though
> is a *release*.
>
> Using the example you pointed me to the other day, you can look at 3  
> different
> versions of the Django FAQ:
>
> http://docs.djangoproject.com/en/dev/faq/
> http://docs.djangoproject.com/en/1.0/faq/
> http://docs.djangoproject.com/en/1.1/faq/

I don't think it's nearly as unmanageable as has been suggested.

I think with using the collective.developermanual it's possible to  
have many versions of the developer manual and even backport  
documenation fixes to older branches. Each version will just be  
overwritten with changes out of the appropriate svn branch nightly.

The plone user manual could be versioned for major versions if we  
decide to not backport any enhancements to older versions. I think  
thats fair enough since the manual is already very good and most new  
changes will be reflecting new features anyway.

Dito for all the other manuals.

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.

>
> And here is another example, versioned installation docs from Zenoss:
>
> http://community.zenoss.org/community/documentation/official_documentation/installation-guide
>
> We should be doing the same with Plone's documentation, IMHO.
>
>> I think there's some confusion in my mind about this point. I'm not  
>> sure
>> if with "doc release" you mean separate docs or just pointing to  
>> updated
>> ones.
>
> I mean the documentation included in the release, which could come  
> from
> any number of sources. Just because it makes into a release, does not
> mean it disappears from somewhere else e.g. the KB or Collective docs.
>
>> In the first case, as said earlier, maintaining all the previous
>> releases (to fix erratas or add info) can become cumbersome.
>
> If you view making a release as cumbersome, you are right: it is.
> Developing and releasing Plone is cumbersome too :-p.
>
>> I think that, for now, we can just use the appropiate field to  
>> indicate
>> that certain documents apply to Plone 4 and create a collection from
>> them, or manually link them all (not so many) in a page if needed.
>
> Right, that is the status quo. If we start *releasing* documentation
> for Plone though, I'd guess the soonest release we could do it with,
> and most likely target is 4.1.
>
>> Only for new stuff, like existing PLIPs are for new features.
>
> No, not only for new stuff (documentation), but for a particular
> release (of existing documentation). A PLIP is an improvement
> proposal and take many forms e.g. adding, removing, restructuring.
> It would probably be pretty easy to mimick the FWT PLIP process,
> or join it.
>
>> [...]
>
>> If everybody believes that the figure of a "doc team leader" is
>> necessary, meaning the one who manages the efforts and levels the  
>> field
>> so everybody can contribute easily, but not the one who writes all  
>> the
>> documentation (which should be written by the developers themselves),
>> I'd be glad to serve.
>
> Great! I think that makes you the doc team leader (technically
> release manager, in FWT-speak). Note: I have made this proposal to
> the Foundation board and members and I expect a response, but I'm not
> going to pursue it. I hope they decide in favor and that you and/or
> future "documentation release managers" decide to pursue it.
> But either way, it's been a productive conversation IMHO.
>
>> Cheers,
>> -- israel
>>
>>
>> ------------------------------------------------------------------------------
>> Download Intel&#174; Parallel Studio Eval
>> Try the new software tools for yourself. Speed compiling, find bugs
>> proactively, and fine-tune applications for parallel performance.
>> See why Intel Parallel Studio got high marks during beta.
>> http://p.sf.net/sfu/intel-sw-dev
>> _______________________________________________
>> 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


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