[ZDP] Re: [Zope] Giving up in frustration

[Martijn Faassen]

Hadar Pedhazur wrote:
> > I doubt that the documentation writer DC has hired will
> > ever catch up in the current climate.
> 
> You're correct. It was my hope that the ZDP effort would
> help to ameliorate that problem. I, for one, think they've
> made a very admirable dent.
[snip]
> To me, the problem with the docs were not a complete lack of
> documentation, but rather a lack of organization.
> Unfortunately, that allowed us to cede such an important
> effort to a vigorous group of volunteers. I say
> "unfortunately", because since then, 2.0 introduced so many
> new concepts, that clearly reorganizing the old docs alone,
> would not give us the clarity that we would need.

Thanks; unfortunately the ZDP effort also currently is in stasis. This is
because we all tend to prefer developing with Zope instead of writing
documentation, we're trying to learn ourselves, and we're volunteers anyway.

The ZDP needs someone to push things forward. In the past, that was me, I
think -- but I lack the time right now, I'm afraid. Working in the ZDP can
however be rewarding; documenting something may be difficult if you don't
know about it yet, but it's also an excellent way to learn more about it.
Also it's just nice to see the docs grow, and to have them, of course.

Part of the problem (for me) is that things are currently too difficult. We
lack a good FAQ tool, for instance. Me editing text files didn't really work
well -- I became a bottleneck, and I gave up. We have ZTables to implement a
FAQ tool, but the ZDP site runs on Zope 1, and we're all busy with Zope 2
right now. And the Portal Toolkit is coming, which may offer better features
still, etc. We got into a deadlock there, I think. Anyway, if it were easier
for me and others to add FAQs and so on, I think I'd put more time in it.
The Zope Portal Toolkit seems to be a step in the right direction with the
way it allows you to add HOWTOs.

I've also seen too little communication with the person responsible for docs
at Digital Creations; the ZDP doesn't seem to have heard much (I did send an
email). Some organization talent and simply grunt editing of community
provided docs would be very helpful to the ZDP, I think.

In general, the community is perfectly capable of turning out lots of
unpolished documentation (we haven't seen anything near the full potential
of that yet), but not so capable of editing and organizing these. I like
writing and editing docs myself, but organizing them coherently I don't like
doing so much, especially if I need to do it by hand.

Anyway, Hadar, I agree with your analysis. I was just trying to describe my
set of diffuse feelings from the ZDP point of view. I've felt vaguely guilty
for not doing more about the ZDP.

All this criticism aside, I do think Digital Creations in general is doing
an excellent job, both community wise (you people are helpful and friendly
in general -- I didn't percieve as much nastiness in this thread as others
saw, apparently :), and in the way you people come out with the most
amazingly nice stuff that we all can really drool over. This rapid
development, though sometimes bad for documentation, is also very impressive
and very attractive at the same time. Don't stop that; it's fun! (though
some stabilization is of course desirable after the mad rollercoaster ride
towards Zope 2 -- but development can go quite quickly on products that
_build_ on Zope 2).

Just organize the documentation effort better. Our biggest need, I think, is
an organization of the documentation infrastructure. Someone needs to be get
pretty radical there -- ripping apart everything and putting it all together
again in a better way. I'll definitely be around to give my help.

Regards,

Martijn