Re: collective.developermanual is now on plone.org

Hi,

The idea is to have one developer manual right? Otherwise it's going  
to be confusing where to put what.

The way I see it we have two potential contenders of the "one" plone  
development manual, the existing plone.org manual and the new  
collective manual. Each has a different update process but both are  
trying to be the same thing.

I'm not sure what the process is for making this decision. Are there  
still documentation team meetings where stuff is decided. Is this open  
for debate? Anyone know?

Hopefully I've answered Israel's questions about structure and quality  
of the collective documentation further down. The options I can think  
of are:

a) Let both manuals exist for a couple of months side by side in the  
manuals area and then decide which to keep after that. Basically  
experiment with the update process and see what produces better  
content and which contributors and readers prefer.

b) Let both manuals exist for a couple of months, one in manuals  
section, one in kb, and then decide which to keep after that

c) Decide on the collective manual and begin moving all content from  
the current plone.org manual into it. If we change our minds later we  
can always just keep the plone conversion and revert it to a normal  
plone manual.

d) Decide the plone.org manual is the way forward and begin moving all  
content from the collective manual into the plone.org manual. Let the  
collective manual go somewhere else (probably just stay on Mikko's  
site) or just give up on it.

e) Mix and match. In theory I can modify the upload script to follow  
redirects (chances are it already does this). That means it's possible  
move content out of the plone version of teh collective manual, put it  
into the plone.org manual and yet still have it be regularly  
overwritten by updates from the collective. Care would need to be  
taken for editors to know which are "collective" pages of the manual  
and which are plone editible pages, but I'm just noting this is  
possible.



On 26/01/2010, at 3:55 AM, Israel Saeta Pérez wrote:

> Martin Aspeli wrote:
>> Dylan Jay wrote:
>>> Hi,
>>>
>>> The manual is now uploaded to the knowledgebase area[1]. I'm  
>>> assuming
>>> that the redesign will get rid of the authors attributions as that  
>>> no
>>> longer makes sense right? If not I'll get Mikko to reupload it as  
>>> it's
>>> mainly his work.
>
> Great work! Congrats! I thought I'd never see this done.
>
>>> All the code for uploading will be in the buildout in
>>> collective.developermanual shortly. Next step will be to setup  
>>> regular
>>> reuploads every night. Of course if anyone wants to contribute to  
>>> the
>>> manual just read [2]
>
> Is it possible to make the manual non-editable for non-privileged  
> users
> so nobody starts editing its contents TTW by mistake?

I can't answer for sure but I'm guessing it just adds complexity to  
have a special workflow for one item. Since the pool of manual editors  
is smaller it might be easier to just educate them not the edit this  
manual

I also remember hearing that the plan is to remove adding the  
PHCManual type from the kb area so this is another reason why this  
manual in the kb area might not make sense.

>
>>> [...]
>>
>>  - As Alex said, it's probably better as a manual than a kb article.
>> This really ought to be the basis for "the" manual for Plone  
>> development
>> in general.
>
> The reason I suggested to leave this collective.developermanual in the
> KB for is mainly the difference in contribution policies between the
> manuals and the KB area. I know Mikko and many others want this manual
> to be freely editable and without any QA review process, and that it
> will potentially contain incomplete draft stuff, so either we:

I think the main idea was to allow anyone with enough development mojo  
to be able to contribute to the manual as naturally as possible (plus  
also have the flexibility to pull in existing code documentation as  
necessary). Separately from this Mikko and others argued for something  
like the kb in addition so perhaps this is where the confusion came in?

There could be a QA review process for the collective manual.

In svn we have branches, so we could use a review process where  
editors could review any new documentation before it's merged into the  
plone3 branch or plone4 branch.

Alternatively we have the publishing step where it could be reviewed  
before an uploading the content into plone.

Even if we use use neither of those processes above the mere fact that  
someone has to be bothered to gain collective svn access and then edit  
the reST which should filter out most "bad" contributions (touch wood).



>
> a) Make an exception to the manuals area policies and allow this
> collective.developermanual to live there. This would mean that we  
> would
> have a manual in the manuals area that wouldn't need any contributor
> agreement to be edited, but only collective rights access, and so we
> would have to be very careful about copyright confusions.

Copyright is a really good point. Again not 100% sure but I'd say that  
the way the collective works is that by contributing to existing code  
in there you are accepting that you are giving your rights up and  
accepting whatever license and copyright is already attached to that  
code. I can't see a license in collective.developermanual but I don't  
see a problem with adding a creative commons one? Mikko?

>
> b) Leave it in the KB and don't break the main policies.

>
> Please keep in mind that the KB, at least from my point of view, is
> *not* designed to be a second-rank, low-quality documentation area.  
> It's
> just a solution to allow people who want to contribute free-form
> documentation without having to fight with the manuals structure.

collective.developermanual is a manual structure and is designed not  
for people who want free-form documentation but rather who want to  
fight the manuals structure.

>
>
>>  - We shouldn't call it 'collective.developermanual'. That's the name
>> of a Python package where we put some reST source code. It has no
>> meaning to the intended audience and it's a terrible title. I'd just
>> call it the "Plone Python Development Manual" or some such.
>
> I agree. Should we call up a small poll on the title of this manual?



>
> -- israel
>
>
> ------------------------------------------------------------------------------
> Throughout its 18-year history, RSA Conference consistently attracts  
> the
> world's best and brightest in the field, creating opportunities for  
> Conference
> attendees to learn about information security's most important  
> issues through
> interactions with peers, luminaries and emerging and established  
> companies.
> http://p.sf.net/sfu/rsaconf-dev2dev
> _______________________________________________
> Plone-docs mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/plone-docs


------------------------------------------------------------------------------
The Planet: dedicated and managed hosting, cloud storage, colocation
Stay online with enterprise data centers and the best network in the business
Choose flexible plans and management services without long-term contracts
Personal 24x7 support from experience hosting pros just a phone call away.
http://p.sf.net/sfu/theplanet-com