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