[Zope-dev] On documentation: how about a Catalog of *every* how-to on zope.org?

[Joe Grace]

I know that the how-to list is available, but the list only seems to include
select how-to's.  I would love to be able to look at all how-tos in one fell
swoop (even if they're not great, for Zope 1.0, etc.).  I could not find the
(old) Product Tutorial until this thread.  It includes some invaluable
information on exactly *what* the legendary Zope Debugger is (i.e.,
ZPublisher.Test module).  Woo-hoo.

I would love a simple ZCatalog button that pulls up everything in user
directories without being selective about it!

This could help speed up aggressive, voracious newbies considerably.  Also,
it could help provide some background for style guides as many people's
styles of docs would be available at a touch of a URL.

Thanks for listening,

= Joe =


Martijn Faassen wrote:

> Hi there,
>
> Many of us are developing products for Zope; either in pure python, pure
> ZClasses, or a combination. I'd like to make the products I'm making as
> 'Zope compliant' as possible; that is, they should use:
>
> * the standard Zope web interface
> * they should follow the standard Zope security conventions
> * when possible, they should implement a number other standard Zope
> interfaces, such as the properties interface and the object manager
> interface.
>
> The problem is that there is, as far as I know, no:
>
> * standard Zope web interface definition
> * standard Zope security conventions description
> * description of other standard Zope interfaces
>
> This is in part a documentation problem, but in part it's simply that
> the standards are probably undefined. The classes to inherit from are
> there in many cases, but I personally am in the dark concerning many
> issues. I just practice 'voodoo programming' where I just do stuff
> because I know I have to, but haven't a clue why. This is bad.
>
> So, could we start somekind of process in order to define what it means
> to be 'Zope compliant'. I have in mind:
>
> * standards documents
>
> * guidelines documents
>
> * motivations and explanations of the standards and guidelines.
>
> * tutorials and examples, such as products like the 'Boring' product
> that give working and compliant examples.
>
> * a peer review process; developers review each other's product code for
> standard compliance. Product users can do part of the reviewing as well.
>
> * Perhaps somekind of 'official approval stamp', that at least gives a
> clue that the product you're using is mature and complaint. Though we
> should watch out that this process wouldn't slow down development.
>
> Doing this could help us in many ways; we learn more about how to write
> a product, we learn more about how to write a *good* (secure, usable)
> product, and finally the development of Zope itself is helped by
> pointing out what people use/should use, and suggestions for future
> directions.
>
> Any comments, ideas?
>
> Regards,
>
> Martijn
>
> _______________________________________________
> Zope-Dev maillist  -  Zope-Dev@zope.org
> http://lists.zope.org/mailman/listinfo/zope-dev
> **  No cross posts or HTML encoding!  **
> (Related lists -
>  http://lists.zope.org/mailman/listinfo/zope-announce
>  http://lists.zope.org/mailman/listinfo/zope )