plone-docs — Discussion about the Plone documentation

Re: [Plone-docs] updated collective.developermanual: Generic Setup upgrade steps

[Israel S. P. <duk...@gm...>]

I'd check the ones coming from:
https://dev.plone.org/collective/log/collective.developermanual/trunk

-- israel


2010/7/5 Dylan Jay <dy...@dy...>

> Anyone know where to get a rss feed for svn commits to the
> collective.developermanual?
>
> Dylan Jay
> Technical solution manager
> PretaWeb 99552830
>
> On 04/07/2010, at 9:08 PM, Israel Saeta Pérez <duk...@gm...> wrote:
>
> > On 07/01/2010 02:30 PM, Kees Hink wrote:
> >> Dear plone-docs list,
> >>
> >> I've written a bit about installing an upgrade step in the
> developermanual. The
> >> changeset is
> >>
> https://dev.plone.org/collective/changeset/120050/collective.developermanual/trunk/source
> >>
> >>
> >> This is largely based on Maurits van Rees' blog post at
> >> http://maurits.vanrees.org/weblog/archive/2009/12/catalog. (The manual
> itself
> >> does not seem like the right place to give credit.)
> >>
> >> Is there anyone systematically reviewing all new contributions? If not:
> if
> >> someone would care to review, that would be great!
> >
> >
> > Hi Kees,
> >
> > I don't think anyone (expect, perhaps, Mikko?) is systematically
> > reviewing contributions to the collective developer docs. Due to the
> > nature of this manual, anyone can contribute to it without following a
> > reviewing process to ensure accuracy and all.
> >
> > Anyway, if you want someone to review it, I'd ask Maurits directly, or
> > any other who has written upgrade steps for Plone (davisagly, esteele?).
> >
> > Thanks for contributing!
> > -- israel
> >
> >
> >
> ------------------------------------------------------------------------------
> > This SF.net email is sponsored by Sprint
> > What will you do first with EVO, the first 4G phone?
> > Visit sprint.com/first -- http://p.sf.net/sfu/sprint-com-first
> > _______________________________________________
> > Plone-docs mailing list
> > Plo...@li...
> > https://lists.sourceforge.net/lists/listinfo/plone-docs
>

Re: [Plone-docs] updated collective.developermanual: Generic Setup upgrade steps

[Kees H. <hi...@gw...>]

Hi Israel,

Thanks for this. Maurits has already provided me with some feedback.

Kees

I've received some feedback

On 07/04/2010 01:08 PM, Israel Saeta Pérez wrote:
> On 07/01/2010 02:30 PM, Kees Hink wrote:
>> Dear plone-docs list,
>>
>> I've written a bit about installing an upgrade step in the developermanual. The
>> changeset is
>> https://dev.plone.org/collective/changeset/120050/collective.developermanual/trunk/source
>>
>>
>> This is largely based on Maurits van Rees' blog post at
>> http://maurits.vanrees.org/weblog/archive/2009/12/catalog. (The manual itself
>> does not seem like the right place to give credit.)
>>
>> Is there anyone systematically reviewing all new contributions? If not: if
>> someone would care to review, that would be great!
> 
> 
> Hi Kees,
> 
> I don't think anyone (expect, perhaps, Mikko?) is systematically 
> reviewing contributions to the collective developer docs. Due to the 
> nature of this manual, anyone can contribute to it without following a 
> reviewing process to ensure accuracy and all.
> 
> Anyway, if you want someone to review it, I'd ask Maurits directly, or 
> any other who has written upgrade steps for Plone (davisagly, esteele?).
> 
> Thanks for contributing!
> -- israel
> 
> 
> ------------------------------------------------------------------------------
> This SF.net email is sponsored by Sprint
> What will you do first with EVO, the first 4G phone?
> Visit sprint.com/first -- http://p.sf.net/sfu/sprint-com-first

Re: [Plone-docs] Documentation for ZopeSkel Efforts

[Alex C. <ac...@ac...>]

Hi,


On 7/4/10 7:02 AM, in article i0ppod$ub1$1...@do..., "Israel Saeta
Pérez" <duk...@gm...> wrote:

> On 06/28/2010 09:19 PM, Elizabeth Leddy wrote:
>> Hi all -
>> 
>> I want to add some official documentation for zopeskel - where is the
>> best place to do that? I know collective docs is the new hotness but I'm
>> not sure who/what/how on updating that. The zopeskel stuff has several
>> contributors so letting everyone have access would be ideal.
> 
> Hey Elizabeth,
> 
> sorry for so late reply - my university network filters the NNTP port. :(
> 
> Being ZopeSkel a separated well-delimited package, I'd put its
> documentation either inside the proper package README.txt file,
> http://svn.plone.org/svn/collective/ZopeSkel/trunk/README.txt

Or?

> 
> 
> This would make the documentation available directly in the PyPI page.

You can also host documentation on PyPI by uploading a zip file that has a
top level index.html (e.g. Sphinx docs), but I have a feeling eleddy is
looking for a more "central" place to host the ZopeSkel docsŠ

In fact, this reminds me of one of my yet-to-be-proposed-proposals I am
considering for 4.1: Include ZopeSkel in Plone core.

I won't fully propose it now (and the proposal would go to dev.plone.org as
a plip), but in short:


Mini-proposal: Include ZopeSkel in Plone core.
=============================================

Why?
---

Because (AFAIK) we eventually want Plone to be able to create packages TTW
with the push of a button (a la Zenoss' ZenPacks). And ZopeSkel is the
closest thing we've got to that right now. Also, it tends to not receive the
proper care it deserves and incorporating it into the core would fix that.
We could even enforce things like "every developer who adds a feature must
update ZopeSkel to make that feature is easily customizable on the fs".


Alex



> 
> -- israel
> 
> 
> ------------------------------------------------------------------------------
> This SF.net email is sponsored by Sprint
> What will you do first with EVO, the first 4G phone?
> Visit sprint.com/first -- http://p.sf.net/sfu/sprint-com-first

-- 
Alex Clark · http://aclark.net
Author ‹ Plone 3.3 Site Administration · http://aclark.net/admin

Re: [Plone-docs] Documentation for ZopeSkel Efforts

[Alex C. <ac...@ac...>]

Eleddy!

On 6/28/10 3:19 PM, in article
AAN...@ma..., "Elizabeth
Leddy" <el...@um...> wrote:

> Hi all - 
> 
> I want to add some official documentation for zopeskel - where is the best
> place to do that? I know collective docs is the new hotness but I'm not sure
> who/what/how on updating that.
> 

It¹s in the collective, so collective rules apply AFAIK.
> 
> 
>  The zopeskel stuff has several contributors so letting everyone have access
> would be ideal.
> 
> Thanks!
> 
> Liz (eleddy)
> 
> 
> ------------------------------------------------------------------------------
> This SF.net email is sponsored by Sprint
> What will you do first with EVO, the first 4G phone?
> Visit sprint.com/first -- http://p.sf.net/sfu/sprint-com-first
> 
> _______________________________________________
> Plone-docs mailing list
> Plo...@li...
> https://lists.sourceforge.net/lists/listinfo/plone-docs


-- 
Alex Clark · http://aclark.net
Author ‹ Plone 3.3 Site Administration · http://aclark.net/admin

Re: [Plone-docs] updated collective.developermanual: Generic Setup upgrade steps

[Israel S. P. <duk...@gm...>]

On 07/01/2010 02:30 PM, Kees Hink wrote:
> Dear plone-docs list,
>
> I've written a bit about installing an upgrade step in the developermanual. The
> changeset is
> https://dev.plone.org/collective/changeset/120050/collective.developermanual/trunk/source
>
>
> This is largely based on Maurits van Rees' blog post at
> http://maurits.vanrees.org/weblog/archive/2009/12/catalog. (The manual itself
> does not seem like the right place to give credit.)
>
> Is there anyone systematically reviewing all new contributions? If not: if
> someone would care to review, that would be great!


Hi Kees,

I don't think anyone (expect, perhaps, Mikko?) is systematically 
reviewing contributions to the collective developer docs. Due to the 
nature of this manual, anyone can contribute to it without following a 
reviewing process to ensure accuracy and all.

Anyway, if you want someone to review it, I'd ask Maurits directly, or 
any other who has written upgrade steps for Plone (davisagly, esteele?).

Thanks for contributing!
-- israel

Re: [Plone-docs] Documentation for ZopeSkel Efforts

[Israel S. P. <duk...@gm...>]

On 06/28/2010 09:19 PM, Elizabeth Leddy wrote:
> Hi all -
>
> I want to add some official documentation for zopeskel - where is the
> best place to do that? I know collective docs is the new hotness but I'm
> not sure who/what/how on updating that. The zopeskel stuff has several
> contributors so letting everyone have access would be ideal.

Hey Elizabeth,

sorry for so late reply - my university network filters the NNTP port. :(

Being ZopeSkel a separated well-delimited package, I'd put its 
documentation either inside the proper package README.txt file,
http://svn.plone.org/svn/collective/ZopeSkel/trunk/README.txt


This would make the documentation available directly in the PyPI page.

-- israel

[Plone-docs] updated collective.developermanual: Generic Setup upgrade steps

[Kees H. <hi...@gw...>]

Dear plone-docs list,

I've written a bit about installing an upgrade step in the developermanual. The
changeset is
https://dev.plone.org/collective/changeset/120050/collective.developermanual/trunk/source


This is largely based on Maurits van Rees' blog post at
http://maurits.vanrees.org/weblog/archive/2009/12/catalog. (The manual itself
does not seem like the right place to give credit.)

Is there anyone systematically reviewing all new contributions? If not: if
someone would care to review, that would be great!

Kees

[Plone-docs] Documentation for ZopeSkel Efforts

[Elizabeth L. <el...@um...>]

Hi all -

I want to add some official documentation for zopeskel - where is the best
place to do that? I know collective docs is the new hotness but I'm not sure
who/what/how on updating that. The zopeskel stuff has several contributors
so letting everyone have access would be ideal.

Thanks!

Liz (eleddy)

Re: [Plone-docs] improvment of upgrade guide, 3;x to 4. Validators

[Israel S. P. <duk...@gm...>]

On 06/18/2010 04:33 PM, toutpt wrote:
>
> A word about the
> http://plone.org/documentation/manual/upgrade-guide/version/upgrading-plone-3-x-to-4.0/updating-add-on-products-for-plone-4.0/validators
>
> We have just fix (me and khink) Products.CompoundField to support both:
> http://dev.plone.org/archetypes/changeset/12636
>
> The code is not that great but Products.validation doesn't have both (zope2
> and zope3) interfaces.


Hi Jean-Michel,

why don't you use something like
http://dev.plone.org/collective/changeset/100927 ?

Isn't Products.validation.interfaces.ivalidator a z2-style interface and 
Products.validation.interfaces.IValidator.IValidator a z3 one?

-- israel

[Plone-docs] improvment of upgrade guide, 3;x to 4. Validators

[toutpt <to...@gm...>]

A word about the
http://plone.org/documentation/manual/upgrade-guide/version/upgrading-plone-3-x-to-4.0/updating-add-on-products-for-plone-4.0/validators

We have just fix (me and khink) Products.CompoundField to support both:
http://dev.plone.org/archetypes/changeset/12636

The code is not that great but Products.validation doesn't have both (zope2
and zope3) interfaces.



-----
Jean-Michel François aka toutpt
http://toutpt.wordpress.com
http://twitter.com/toutpt

-- 
View this message in context: http://plone.293351.n2.nabble.com/improvment-of-upgrade-guide-3-x-to-4-Validators-tp5195502p5195502.html
Sent from the Documentation Team mailing list archive at Nabble.com.

Re: [Plone-docs] Working on the PHC product

[Israel S. P. <duk...@gm...>]

On 06/08/2010 02:58 AM, Alex Clark wrote:
> On 2010-06-07, Israel Saeta Pérez<duk...@gm...>  wrote:
>> b) Refactor the whole PHC again, rewriting it from scratch to be as
>> light-weight as possible and Plone 4 compatible. The migration could be
>> accomplished using transmogrifier. I guess Rok Garbas could help us
>> here. This would need several weeks this summer, and lots of testing.
>>
>> What do you think is best?
>
> I think a re-factor for PSC/PHC has generally been decided against. Last year some time
> I joked about re-writing PSC w/Dexterity types and people said "Yeah!" Then they said
> "No! I was kidding, that is insane." Or something to that effect.
>
> In other words, a refactor would be great, but it's probably too much work.
>
> So, GO GO GO on the bug fixes!

If the refactoring is considered too much work, do we plan to keep 
patching PSC/PHC in the long term? Or get rid of them at some point, 
somehow?


> FWIW, David Glick mentioned the idea of a plone.org sprint some time this month which
> I think is a great idea because I need to get something on the calendar in order to
> be able to devote serious time to it.

Count me in!

-- israel

Re: [Plone-docs] Working on the PHC product

[Alex C. <ac...@ac...>]

On 2010-06-07, Israel Saeta Pérez <duk...@gm...> wrote:
> b) Refactor the whole PHC again, rewriting it from scratch to be as 
> light-weight as possible and Plone 4 compatible. The migration could be 
> accomplished using transmogrifier. I guess Rok Garbas could help us 
> here. This would need several weeks this summer, and lots of testing.
>
> What do you think is best?

I think a re-factor for PSC/PHC has generally been decided against. Last year some time
I joked about re-writing PSC w/Dexterity types and people said "Yeah!" Then they said
"No! I was kidding, that is insane." Or something to that effect.

In other words, a refactor would be great, but it's probably too much work.

So, GO GO GO on the bug fixes! 

FWIW, David Glick mentioned the idea of a plone.org sprint some time this month which
I think is a great idea because I need to get something on the calendar in order to
be able to devote serious time to it.

> -- israel
>
>
> ------------------------------------------------------------------------------
> ThinkGeek and WIRED's GeekDad team up for the Ultimate 
> GeekDad Father's Day Giveaway. ONE MASSIVE PRIZE to the 
> lucky parental unit.  See the prize list and enter to win: 
> http://p.sf.net/sfu/thinkgeek-promo


-- 
Alex Clark · http://aclark.net
Author — Plone 3.3 Site Administration · http://aclark.net/admin

[Plone-docs] Working on the PHC product

[Israel S. P. <duk...@gm...>]

Hello list,

I've recently had a look at the list of open issues for the Plone Help 
Center 
(http://plone.org/products/plonehelpcenter/issues/poi_issue_search?state=unconfirmed&state=open&state=in-progress). 
The list is quite long, but I would expect some of the reported issues 
to be old ones that have been fixed or work-arounded in recent PHC versions.

Anyway, being PHC a core component of plone.org, I think we need to 
spend some time on it. The product is quite old and has been refactored 
at least once (by Steve McMahon) to make it more Plone 3 ready.

I know that Alex Clark is eager to upgrade plone.org to Plone 4 not very 
late (the previous upgrade to Plone 3 took place quite late after it was 
released). So I think we have two options:

a) Go through the bug tracker and try to fix the current important open 
issues. Upgrade the code to be compatible with Plone 4 (I've already 
done most of the work in a branch).

b) Refactor the whole PHC again, rewriting it from scratch to be as 
light-weight as possible and Plone 4 compatible. The migration could be 
accomplished using transmogrifier. I guess Rok Garbas could help us 
here. This would need several weeks this summer, and lots of testing.

What do you think is best?

-- israel

Re: [Plone-docs] New hot Plone 4 User Manual

[Israel S. P. <duk...@gm...>]

On 05/18/2010 09:13 PM, Israel Saeta Pérez wrote:
> Hello John,
>
> well spotted! This is certainly not the intended behavior. Actually, I
> reckon this is a bug introduced by me in the PHC code while trying to
> fix the erroneus next/previous behavior.
>
> In the previous version,
> http://dev.plone.org/collective/browser/Products.PloneHelpCenter/trunk/Products/PloneHelpCenter/browser/nextprevious.py?rev=86434#L153
>
> restricts the content-types eligible for the next/previous links, but
> this filtering was eliminated in the current version. I would need some
> time to fix the bug and write proper tests to ensure this doesn't happen
> again. I'm too busy with university homework and all now, but if anyone
> can help with this (apart from discussing ;) I'd greatly appreciate it.


Fixed! :)
http://dev.plone.org/collective/changeset/118768

-- israel

Re: [Plone-docs] Add depth to Plone Help Center Navigation tree

[Israel S. P. <duk...@gm...>]

On 05/27/2010 01:33 PM, stefanx wrote:
> Am 14.07.2008 14:25, schrieb MarcoDT:
>>
>> Hello,
>>
>> we've a implemented basic Plone 3.1.1 installation with Plone Help Center
>> 1.5.
>>
>> We wanted to add more depth to the reference manual section, but it seems
>> that only the first level is shown. I've already check the general
>> navigation tree depth, but it is set to 0, so it shouldn't be the problem.
>>
>> A the moment it doesn't show subsections nor pages in the navigation tree.
>>
>> Sorry If the question has been already posted but I've tried several times
>> to look at documentation and support forum but I haven't found any answer
>> (probably I've searched it in the wrong way given my limited Plone/Zope
>> knowledge).
>>
>> Thank you in advance.
>
> Ok, this mail is nearly two years old, but the problem remains.
> This seems to be a bug in PHC.
>
> Any ideas ?


Have you tried updating to the last PHC version? Even if it's not a 
final one, we're using it at plone.org.

-- israel

Re: [Plone-docs] PloneHelpCenter navigation Problem

[stefanx <st...@lr...>]

Am 27.05.2010 10:40, schrieb stefanx:
> 
> Hello,
> 
> I've added the plonehelpcenter (3.0b3) reference manual
> item to my pages and then added the content types leaf page,
> reference manual section and reference manual in
> Navigation Settings --> Displayed content types.
> 
> But only the reference manual item itsself is displayed
> in navigation, not section or leaf page.


Sorry, I've solved the problem, but I don't know exactly how :-/

Re: [Plone-docs] Add depth to Plone Help Center Navigation tree

[stefanx <st...@lr...>]

Am 14.07.2008 14:25, schrieb MarcoDT:
> 
> Hello,
> 
> we've a implemented basic Plone 3.1.1 installation with Plone Help Center
> 1.5.
> 
> We wanted to add more depth to the reference manual section, but it seems
> that only the first level is shown. I've already check the general
> navigation tree depth, but it is set to 0, so it shouldn't be the problem.
> 
> A the moment it doesn't show subsections nor pages in the navigation tree.
> 
> Sorry If the question has been already posted but I've tried several times
> to look at documentation and support forum but I haven't found any answer
> (probably I've searched it in the wrong way given my limited Plone/Zope
> knowledge).
> 
> Thank you in advance.

Ok, this mail is nearly two years old, but the problem remains.
This seems to be a bug in PHC.

Any ideas ?

Stefan

[Plone-docs] PloneHelpCenter navigation Problem

[stefanx <st...@lr...>]

Hello,

I've added the plonehelpcenter (3.0b3) reference manual
item to my pages and then added the content types leaf page,
reference manual section and reference manual in
Navigation Settings --> Displayed content types.

But only the reference manual item itsself is displayed
in navigation, not section or leaf page.

Any ideas ?

Stefan

Re: [Plone-docs] Tasks for Sorrento Sprint

[Israel S. P. <duk...@gm...>]

On 05/22/2010 03:46 PM, Israel Saeta Pérez wrote:
> Hello list,
> I'm close to Venice now and I've not had the time to garden the current
> documentation tickets. Could anyone please spend half an hour looking at
> the current list of tickets (https://dev.plone.org/plone/report/8) and
> marking the ones you think are doable during the Sorrento Sprint as
> "SorrentoSprint2010"? You can also open new tickets or divide existing
> ones into smaller bits. The sprint starts next Thursday (IIRC), so
> there's no hurry.
> Thank you all in advance!
> -- israel


I've already tagged some tasks: http://ur1.ca/03mr8

-- israel

[Plone-docs] Tasks for Sorrento Sprint

[Israel S. P. <duk...@gm...>]

Hello list,

I'm close to Venice now and I've not had the time to garden the current
documentation tickets. Could anyone please spend half an hour looking at the
current list of tickets (https://dev.plone.org/plone/report/8) and marking
the ones you think are doable during the Sorrento Sprint as
"SorrentoSprint2010"? You can also open new tickets or divide existing ones
into smaller bits. The sprint starts next Thursday (IIRC), so there's no
hurry.

Thank you all in advance!

-- israel

Re: [Plone-docs] Proposal to create multiple PHCs inside a top level /documenation folder

[Raphael R. <r....@bi...>]

Larry Pitcher wrote:
> Hi,
> 
> I'm not on the doc team, but Alex's idea makes sense to me. It follows 
> the same pattern as the Apache docs, so it's not like it's never been 
> tried before :-)

Hi,

I didn't follow the full discussion but from what
I understood so far people are concerned about
providing URLs like

   docs/manual/4.0/...
   docs/manual/3.3.5/...

would require duplicating contents thereby creating
a maintenance nightmare.

Has it been considered to use alternative means
to achieve the same thing like (i) topics - customized
if needed or (ii) clever traversers based on, e.g.,
how doc items are tagged? (Quills provides an example
for the latter to make blog posts available under
"date-like" URLs even though they are all in the same
folder.)

Just a thought,

	Raphael






> 
> my $0.02
> 
> Larry Pitcher
> 

Re: [Plone-docs] Proposal to create multiple PHCs inside a top level /documenation folder

[Alex C. <ac...@ac...>]

On 2010-05-21, Israel Saeta Pérez <duk...@gm...> wrote:
> I didn't plan to continue replying to what can become the longest thread 
> in the plone-docs list, but

Heh

> On 05/21/2010 04:54 AM, Alex Clark wrote:
>> Hi Larry,
>>
>> On 2010-05-21, Larry Pitcher<unc...@in...>  wrote:
>>> Hi,
>>>
>>> I'm not on the doc team, but Alex's idea makes sense to me.
>
> Time ago we decided to make a distinction between "doc team" and "doc 
> team editors".
>
> The doc team editors were assigned to certain areas (theming, 
> development, basic use, etc.) and had the responsibility to garden them 
> and review new submission. This responsibility also involved a power, 
> which was the power of taking part on the decisions when something 
> important or controversial had to be decided upon, like happened with 
> the manuals/KB split. It was a sort of collective documentation release 
> manager.

I vaguely remember this. Maybe documenting this process, along with the FWT 
process (which I believe Hanno is working on documenting) would help folks 
on the outside to see in.

> As doc team, I consider that everyone interested in documentation is 
> part of the doc team. Obviously it's not just Anne, Steve and me who 
> write documentation, but many other people, like Mikko or any of the 
> developers who contributed to document their PLIPs.

Right, kind of like the "code team" is not just Eric plus the FWT.

>> I think at least a half a dozen folks on this list have expressed interest
>> in some sort of versioning in response to my two proposals. That's why I am
>> declaring the doc teams failure to address it as "stop energy"
>> and I am moving on ;-)
>
> I don't want anybody to see my opinions as "enlightened absolutism". 
> While I've been proposed once or twice to become a kind of 
> "documentation team leader", I've never been officially appointed (like 
> Eric has been as Release Manager). So I can only give my point of view 
> as someone who has been already working with Plone documentation for a 
> while, specially involved in updating it to include changes related to 
> newer Plone versions, and therefore think my opinion is something valuable.
>
> However, since I'm in no official position to make "political 
> decisions", I accept moving in other directions if a majority of people 
> agrees.
>
> Honestly, it's really sad to see how the few people really working on 
> documentation have historically been target of quite hard critics 
> everytime someone hesitated upon a risky movement. These people 
> hard-worked, and yet found that others feel the documentation is stalled 
> and have great plans to drastically and suddenly improve it. It's not a 
> secret that most of them quit, demoralized from the lack of appreciation 
> for their work.

No doubt, and one of my goals in stirring all this up was to try and find
a way to bring some of that "reward" from the outside (i.e. appreciation).
I hope I have expressed enough my own appreciation.

> When one gives his opinion to try to go the right way and is answered 
> with an "In your opinion.  mine, it is." or "this is stop energy", what 
> one thinks is just to quit and let others free their energy and do 
> things the Right Way.

Well, the goal is to work together, and incorporate everyone's ideas, IMO.
But I agree the doc team has been unfortunately subjected to way too
much "hey what's going on in here, poke, poke".

>> I don't blame them, I mean I get the reason (sort of). But I think *something*
>> could be done to address the concern rather than complete inflexibily,
>> and unwillingness to do anything but declare that they will do nothing.
>
> Untrue, read below.

OK

>> Correct me if I am wrong guys, but the only counter-suggestion I have received
>> from the doc team (Israel and Anne and SteveM AFAICT?) is to be good and start
>> closing doc tickets. :-p
>
> There are other ways to solve the problem of showing what version of 
> Plone a certain approach corresponds to, like using the current PHC 
> metadata (and trying to highlight this info in the presentation) and 
> writing it in the appropriate paragraphs, as we've been doing. This has 
> already been mentioned before.
>
> I suggested to work on current, well identified stuff captured in the 
> form of tickets since I know that everyone loves taking part in big 
> changes that are going to drastically improve the current situation, but 
> very few people takes care of real documentation writing and other more 
> mundane stuff.

Right, and these are good suggestions… I think we will just have to 
agree to disagree on whether or not they address my specific concern.

> I really don't want to spend more time in this politics thing. I don't 
> want to fight against half a dozen of people and keep saying the same 
> arguments over and over again. I want to spend my time in preparing easy 
> tasks for the people in the upcoming Sorrento Sprint to contribute.

Indeed, sorry for the noise.

My one final suggestion is that it usually never hurts to encourage folks to
run with a particular "crazy" idea, and let it run its course on its
own, without telling them your opinion of it (and therefore discouraging
innovation).

IOW, I setup collective-docs.plone.org, which I suspect Mikko and Dylan
are not the biggest fans of, because it kind of short circuits their
long term goals (AFAICT). ;-) But it is relatively harmless, and if 
they asked me to turn it off, I would.

In the same way, like I said, I could create crazy-phc.plone.org as
an experiment, and reorganize all the content i wanted to. It may
be well liked, it or it may go nowhere. But the "spotlight energy"
(i.e. attention from the outside directed in) is thus re-directed
away from doc team list, where it can be destructive (as I
am learning).

The equivalent to this in software land is branches. And if you look
through the collective and plone repos you will find the rotting
corpses of (literally!) hundreds of bad or unfinished ideas. :-)

Ciao

> -- israel
>
>
> ------------------------------------------------------------------------------


-- 
Alex Clark · http://aclark.net
Author of Plone 3.3 Site Administration · http://aclark.net/plone-site-admin

Re: [Plone-docs] Proposal to create multiple PHCs inside a top level /documenation folder

[Israel S. P. <duk...@gm...>]

I didn't plan to continue replying to what can become the longest thread 
in the plone-docs list, but


On 05/21/2010 04:54 AM, Alex Clark wrote:
> Hi Larry,
>
> On 2010-05-21, Larry Pitcher<unc...@in...>  wrote:
>> Hi,
>>
>> I'm not on the doc team, but Alex's idea makes sense to me.

Time ago we decided to make a distinction between "doc team" and "doc 
team editors".

The doc team editors were assigned to certain areas (theming, 
development, basic use, etc.) and had the responsibility to garden them 
and review new submission. This responsibility also involved a power, 
which was the power of taking part on the decisions when something 
important or controversial had to be decided upon, like happened with 
the manuals/KB split. It was a sort of collective documentation release 
manager.

As doc team, I consider that everyone interested in documentation is 
part of the doc team. Obviously it's not just Anne, Steve and me who 
write documentation, but many other people, like Mikko or any of the 
developers who contributed to document their PLIPs.


> I think at least a half a dozen folks on this list have expressed interest
> in some sort of versioning in response to my two proposals. That's why I am
> declaring the doc teams failure to address it as "stop energy"
> and I am moving on ;-)

I don't want anybody to see my opinions as "enlightened absolutism". 
While I've been proposed once or twice to become a kind of 
"documentation team leader", I've never been officially appointed (like 
Eric has been as Release Manager). So I can only give my point of view 
as someone who has been already working with Plone documentation for a 
while, specially involved in updating it to include changes related to 
newer Plone versions, and therefore think my opinion is something valuable.

However, since I'm in no official position to make "political 
decisions", I accept moving in other directions if a majority of people 
agrees.

Honestly, it's really sad to see how the few people really working on 
documentation have historically been target of quite hard critics 
everytime someone hesitated upon a risky movement. These people 
hard-worked, and yet found that others feel the documentation is stalled 
and have great plans to drastically and suddenly improve it. It's not a 
secret that most of them quit, demoralized from the lack of appreciation 
for their work.

When one gives his opinion to try to go the right way and is answered 
with an "In your opinion.  mine, it is." or "this is stop energy", what 
one thinks is just to quit and let others free their energy and do 
things the Right Way.


> I don't blame them, I mean I get the reason (sort of). But I think *something*
> could be done to address the concern rather than complete inflexibily,
> and unwillingness to do anything but declare that they will do nothing.

Untrue, read below.

> Correct me if I am wrong guys, but the only counter-suggestion I have received
> from the doc team (Israel and Anne and SteveM AFAICT?) is to be good and start
> closing doc tickets. :-p


There are other ways to solve the problem of showing what version of 
Plone a certain approach corresponds to, like using the current PHC 
metadata (and trying to highlight this info in the presentation) and 
writing it in the appropriate paragraphs, as we've been doing. This has 
already been mentioned before.

I suggested to work on current, well identified stuff captured in the 
form of tickets since I know that everyone loves taking part in big 
changes that are going to drastically improve the current situation, but 
very few people takes care of real documentation writing and other more 
mundane stuff.

I really don't want to spend more time in this politics thing. I don't 
want to fight against half a dozen of people and keep saying the same 
arguments over and over again. I want to spend my time in preparing easy 
tasks for the people in the upcoming Sorrento Sprint to contribute.

-- israel

Re: [Plone-docs] Proposal to create multiple PHCs inside a top level /documenation folder

[Israel S. P. <duk...@gm...>]

On 05/21/2010 07:12 AM, Alex Clark wrote:
> On 2010-05-20, Alex Clark<ac...@ac...>  wrote:
>> Hi,
>>
>> On 2010-05-20, Israel Saeta Pérez<duk...@gm...>  wrote:
>>> Plone Documentation is not a stalled nor a struggling project.
>>
>> In your opinion.  mine, it is.
>
> OOPS, A small bird in my ear has pointed out that this comment might be considered offensive
> to Israel (who must be given an enormous amount of credit for leading the doc team),
> which was not my intention.
>
> Israel, I apologize! :-)


It sligthly was, yes, but I accept your apologies.


-- israel

Re: [Plone-docs] Proposal to create multiple PHCs inside a top level /documenation folder

[Alex C. <ac...@ac...>]

On 2010-05-20, Alex Clark <ac...@ac...> wrote:
> Hi,
>
> On 2010-05-20, Israel Saeta Pérez <duk...@gm...> wrote:
>> Plone Documentation is not a stalled nor a struggling project. 
>
> In your opinion.  mine, it is.

OOPS, A small bird in my ear has pointed out that this comment might be considered offensive 
to Israel (who must be given an enormous amount of credit for leading the doc team),
which was not my intention.

Israel, I apologize! :-)

I'm only voicing my own personal frustration with the current situation, and
trying to help. Anyway, carry on folks, and keep up the great work! :-)

>> We're 
>> making constant progress in several areas. I can say that documenting 
>> Plone 4 has been an important success, with only 2 PLIPs left (I'll have 
>> to lean on some people) and an User Manual with new Sunburst screenshots 
>> (something that requires a lot of mundane work). We're also preparing 
>> videos for the User Manual (which had not been updated since Plone 2) 
>> and an Installation Guide.
>
> That's great!
>
>> Most of our documentation will apply to both Plone 3 and 4 (and even 
>> 2.5). The parts only applying to Plone 4 have been marked appropriately, 
>> either as a whole like the Plone 4 User Manual, or specifically 
>> mentioning so in the associated paragraph. We are looking for special 
>> styles to tag version-specific stuff so it can be easily recognizable.
>
> Sounds good.
>
>> I'm very concerned with the split you're proposing. For the people 
>> writing documentation, this could mean duplicating (or more) the amount 
>> of work.
>>
>> We care about where the documentation is placed because we want the best 
>> for the project, and reduce the amount of unnecessary work. We're not 
>> just machines to throw a piece of code to document at. If we feel this 
>> is growing the wrong way and we can't get involved into the decisions 
>> because they correspond to the "website team", we'll become demoralized 
>> and just quit.
>
> OK
>
>> This wouldn't work, since current documentation applies to both Plone 3 
>> and Plone 4. As you can see, the process is not stalled. :)
>
> I don't see that. I don't see anyone (at least on this list) understanding
> the process but you and Anne. I could be wrong, of course.
>
>> If we copied and moved the documentation as you suggest, then if I 
>> wanted to document something present in both Plone 4.0 and 3.3.6, I 
>> would have to update the docs in both areas, which would mean double 
>> work. This is one of the strongest points I have against your proposal, 
>> and what makes me dismiss it now.
>
> Welcome to software and documentation.
>
>> If there are problems to identify which Plone version a certain document 
>> applies to, what we have to do is to improve how do we present this 
>> information visually, not to duplicate content and work.
>
> If you say so, I disagree, obviously.
>
>> It would be more effective to correct the giant mistake right away in a 
>> single doc, so the correction would be available immediately, instead of 
>> having to wait for the next release.
>
> Again, "effective" in your opinion.
>
>> I don't want you to see this as "stop energy". This would be like if you 
>> blamed the FWT for rejecting a PLIP which is not well-thought or too 
>> risky. I know you want the best for the documentation, but in this case 
>> the best, as Anne says, is to get the actual work done instead of 
>> performing unnecessary big changes.
>
> It would be hard for me to not see this as stop energy, TBH. Maybe others
> have a different perspective…
>
>> You can take a look at https://dev.plone.org/plone/report/8 and pick any 
>> task, or garden them.
>
> Right.
>
>>
>> -- israel
>>
>>
>> ------------------------------------------------------------------------------
>
>


-- 
Alex Clark · http://aclark.net
Author of Plone 3.3 Site Administration · http://aclark.net/plone-site-admin