On 10/11/05, Stephan Richter <[EMAIL PROTECTED]> wrote: > On Tuesday 11 October 2005 13:24, Jeff Shell wrote: > > I'd really like to give Zope 3 a try, and I keep trying to. The docs > > are just nauseating. They might look good or fine to someone who's > > used Zope for years, but to someone new they're horrid. As I > > mentioned, the site is laid out horribly for someone who wants to > > learn Zope 3. Why is the left bar saturated with links when I just > > want Zope 3? > > > > It's incredibly frustrating and disappointing to hear about all the > > cool stuff you can do in Zope 3, and not see anywhere that shows it > > actually being done with descriptions on how it works, etc. Where are > > the examples? Where are the recipies to "do cool thing X"? > > > > The developers I see talk about Zope are all in companies that use > > it, that have teams that use it, that have tons of actual knowledge > > that doesn't exist on the website. I really really want to give Zope > > 3 a spin, I have a few fairly complex projects I'd like to try out > > with it. How do I get started? > > I would say, buy the books. It is too hard to keep documentation up to date, > if you do not get paid. The alternative are doctests of course, which we have > available as mentioned in my previous mail. Again, I think it is a lack of > manpower, my own included. I would love to update the Web site to the version > of my book that has actually been printed, but I just do not have time. All > it needs is someone to merge the stupid DOC files to the TeX master documents > and it would be online. Note that I already put them in a zope.org-based > repo, so anyone can work on that task.
That was my response to him. But for people evaluating Zope 3, or just starting out and not knowing whether it's a worthwhile technology to continue with, buying a book is probably a non-starter. Some good "quick starts" and recipes would help there. I don't think that the type of documentation that is in a book should be on the web site and maintained constantly. It's too big and too hard, a fact I'm sure you're aware of. The API Doc tool, the books, are all useful things to have once you've really committed to a project. But getting people that far is where zope3.org or maybe zope3rocks.com or something - anything! - would be useful. Instead of trying to update reams of documentation with new features in Zope 3.2, one could post a document like "Zope 3.2 - Introducing zope.formlib" or "Zope 3.2 - deprecated functions" Because, for example, I see the warning about using 'getView - use getMultiAdapter instead', but there's no explanation of how a getView(...) call should be translated into a getMultiAdapter call.. One can figure it out, but it's a couple of lines that could be in a document that many of us here can write.. I just don't want it lost in the desert sands of the wiki. I can find proposals about simplifying the component architecture, but there's no final document about what that simplification really produced and how it affects me. The deprecation machinery is great at telling me about these things (again - I think it's a great feature), but oh man - I think any major architecture like Zope 3 that gets *simpler* in a new version is something to sing about. _______________________________________________ Zope3-dev mailing list Zope3email@example.com Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com