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

Alex Clark wrote:
> On 2010-04-14, Israel Saeta Pérez <[email protected]> wrote:
>> I don't really know how to fight against the lack of motivation among 
>> the people working on documentation, including me. 
> 
> Do you like getting paid? That is what I am proposing. I don't know
> the likelyhood that the PF will buy into this, but it would seed
> a lot of activity I think.

Yes I like getting paid, but I don't know why I've always been less 
hesitating to contribute to unpaid projects. Perhaps because accepting a 
payment means real committing and a lot of responsability.

>> I like to think that 
>> lowering the contribution barrier with the division 
>> manuals/knowledgebase will help, but with the UI work and the 
>> policies/permissions/licenses work apparently stalled, I don't know if 
>> we will manage to see the benefits of the knoweldgebase soon.
> 
> Me neither, and I hate stalls. Find a way to work around it, would be
> my suggestion.

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.

[...]

>>> 0.5. Elect a "doc team", again mirroring the FWT process here.
>> http://plone.org/documentation/kb/documentation-team-editors is the 
>> current list of "doc team editors", and 
>> http://plone.org/documentation/kb/plone-org-documentation-editors-roles-and-responsibilities 
>> their responsabilities as stablished two years ago.
> 
> This reads a bit dated to me, and in fact it says 
>     "This scheme will be replaced in a close future by manual owners. ".

I guess this was written by Veda or Steve when we decided for the 
division manuals/kb, so instead of section owners, we would have manual 
owners (what wouldn't be sooo different anyhow).

> How about this: With each release, the new doc team leader and members decide 
>     their roles, and accounce them to the community.
>
> *shrug*

Sounds good but, as Martin points out, you need a bunch of people 
willing to commit. Currently, the doc-team editors are the ones who have 
committed to a similar task, but we've had more people stepping down 
than working hard.

I assume part of the responsability (for the people not working hard) 
because I know I've not leveled the way of the people who could do the 
work as much as I could. Lazy, bad-structured procrastinator Israel. :P

> I don't know much about how this works within the FWT, just that
> everyone owns something and collectively, eventually, their work 
> forms a 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.


>> We care about everything and have a quite long list of more-or-less 
>> defined tasks at https://dev.plone.org/plone/report/8 .
> 
> The most important thing I can think of is end-user documentation, 
> followed by "integrator" documentation. Developers, at least for now
> can figure it out themselves ;-) (Well, not really but just trying to 
> prioritize).

We've already started to take screenshots for the Plone 4 User Manual, 
with the help of a very productive group of folks summonned by Anne 
Botwell. ;)

> Maybe installation docs, too.

Yep, https://dev.plone.org/plone/ticket/9080 .

>> finished. I cannot say "oh yeah, I've sucessfully documented portlets", 
>> because there will always be use-cases and functions not explained. Some 
>> parts of Plone are almost completely undocumented (e.g. some Plone 3 
>> PLIP-based features). I don't really know how to identify a subset of 
>> tasks and release if it isn't corresponding to a software release.
> 
> Work towards a release. :-) There is only so much to be said about portlets 
> in a Plone 4 end user manual. The marketing peeps already cover "What's new?" 
> AFAIK.

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.

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?

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.

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