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

Hello there,

Alex Clark wrote:
> On 2010-04-15, Israel Saeta Pérez <[email protected]> wrote:
>> 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.

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.


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

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. In the first case, as said earlier, maintaining all the previous 
releases (to fix erratas or add info) can become cumbersome.

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.

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

Only for new stuff, like existing PLIPs are for new features.

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

So far, we've been creating new versions of the Plone User Manual and 
just updating the rest of the documentation, indicating "this feature is 
new in Plone 4" where needed. We can decide for each release, yes. :)


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

Plone 4 doesn't offer any UI for showing links to different versions of 
the document either. I'm talking about something like LinguaPlone but 
for software versions instead of languages. But we can do this manually 
where needed for now.

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.

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