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

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/

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