Re: Proposal to create multiple PHCs inside a top level /documenation folder

On 2010-05-21, Israel Saeta Pérez <[email protected]> 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<[email protected]>  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


------------------------------------------------------------------------------

_______________________________________________
Plone-docs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/plone-docs