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

On 2010-04-15, Israel Saeta Pérez <[email protected]> wrote:
> Yes I like getting paid, but I don't know why I've always been less 
> hesitating to contribute to unpaid projects. 

We all do it, it's human nature. What am I doing writing this email when I have
client work waiting? Etc. :-)

> Perhaps because accepting a 
> payment means real committing and a lot of responsability.

Correct. Sometimes that is appropriate. Sometimes it is not. Only you can
decide if you want to accept the responsibility and challenge.


> I'm already approving every document which is submitted for review to 
> the KB. I need to talk to Steve McMahon about the permission settings in 
> the KB.

The KB is fine but confusing, and subject to stalls induced by PHC and other
"dogbowl" issues. What I am proposing is to produce comprehensive, high
quality documentation in the form of manuals or whatever else makes
sense in combination with a software release.

In other words, here is Plone 4 and here is the associated "doc releases":

- End User Manual
- Knowledge Base
- Developer Guide
- Cheatsheet
- Leaflets
- Whatever

If something is in the way of doing this (e.g. PHC) move it out of the way
and focus on the release.

> If I didn't get it wrong, the work of the FWT is to vote PLIPs, not to 
> work on implementing them. The last is the task of the implementor.

Great point! Using that model, PLIPs come from anywhere and everywhere
and the Doc Team decides on what to include in a release.

So the model would be:

- Alex Clark submits doc PLIP #1, end user manual for Plone 4 and offers
  to help write it.

- Doc team accepts/rejects.

> Well, I guess we could make the manuals release-wise and leave the KB 
> unversioned. Django has release-wise documentation and everybody likes 
> the Django docs. We can "experiment" with this approach.

We can do more than experiment ;-)

> But there are some problems assocciated:
> 1) If there's wrong info/errata in a manual, we would have to fix it in 
> all versions/releases, what is tedious. Are we talking about a manual 
> for each X.y version or just for X?

Work towards a release :-) The doc team leader perhaps in combination
with the FWT leader decides.

> 2) We don't have the necessary PHC infrastructure and UI to present the 
> different versions of the manuals to the users. We could create a folder 
> for each version and copy-paste items to work on new releases, but I 
> don't know how to present this properly in the UI.

Work towards a release :-) If that is the case then I suggest we use
some tools that we don't have to maintain ourselves. We get
Plone 4 "for free" so perhaps eliminating PHC and using Just Plone 4™
would work. But again, the goal is to focus on the release… 


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


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