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

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

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


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