Amos Latteier wrote:
Brian Lloyd wrote:
[snip]
I think that this should be a part of the introductory material for the "how to write a product" documentation...
I agree. I think this is tutorial style information.
No, I don't think this kind of thing belongs hidden inside a tutorial. It doesn't even belong in a reference. The "should" and "shouldn't" aspects of product development should at least be seen as a seperate concept. That will hopefully help you improve everything; products *and* documentation.
I also like the idea of a loose sort of peer review (other than someone just downloading the product, finding out it doesn't work, and posting to the mail lists).
I think that this is a great idea. The main problem with it is that it is a lot of work to review someone's product. I think it would take me a couple hours to go through someone's code and try to figure out how it works and how it could be improved.
That's true. How many clues about useful documentation would you gather from it, though? I'd imagine lots.
I personally don't have this kind of time, but others may.
Nobody does. :) But in practice, we *do* look at each other's code. To write good documentation about coding something, you do need to look at current code for coding practices. To write documentation about an existent API you need to look at the code too. We may not call that code reviewing, but let's.
Yes, that's another way to get the ball running quickly. How do we set this up, though? Some procedures would be in order. I've whipped up a suggestion: ... I think that peer review is a Good Thing - I share the opinion that it should be strictly voluntary and very light weight (in fact, I think that zope-dev would be a fine place for these types of discussions, rather than a separate list). My only caveat is: it will be much easier to "review" a product once there is an official description of what a good product is - so I would say that the immediate burden is on _us_ to get that out. Can you comment on this Amos?
As I stated above, we need to finish and make available more Zope Product tutorial information.
Of course this is very important.
I don't think that we need an official good-Product description.
Why not? Anyway, I am clamoring for a process with the *aim* to generate a 'good product' specification. I don't think we can come up with such a spec now. It's obvious from below that nobody really knows. We simply need a process to find out what it could be. It'll be a moving target, but that doesn't matter.
That said, here's a quick list of what I think a good product should do:
* correctly subclass existing Zope classes
Right. We should have a list of which Zope classes do what, and why you should subclass them, and what does it mean to be 'correct'. And what you should do with them after subclassing them. And what you shouldn't do.
* correctly handle permissions
I think this too needs documentation but also guidelines. What to call the new permissions you come up with? What kind of defaults would you set, and why? What are the _current_ permissions about, and how to use them with your own product? What would be wrong to do? What would introduce security holes? What should I do with my methods? Put _ in front to shield them, or not, and if I don't, do I add it in security? A thousand questions both documentation and guideline oriented.
* correctly handle persistence
I've seen guidelines and doc for this floating around, but I'm still unclear on what my options are and what I shouldn't do.
* present a reasonable HTML UI to users
That conforms to Zope standards. It should similar to the rest of Zope. What do we do when Zope's UI changes (Mozilla, for instance). What will definitely help in that transition process is a good clue what the current HTML UI is actually about.
* present a reasonable API to DTML programmers
Do we know what a 'reasonable' API is?
* include some documentation
Is there some auto documentation tool coming up? How will it work? How will my documentation conform? Are there documentation standards?
A good product mostly is one that works correctly ;-)
That's why I said nobody really knows what a good product is. What does 'work correctly' mean? :) Correctly for end-users, developers, the original developer, who? It should also work consistently, it should fit in with the rest of Zope. We don't know what 'fitting in' means well enough right now.
Of course there are gray areas, like what is a reasonable HTML UI? And how should you decide what methods should be protected by what permissions? For questions like these I agree that we should come up with some recommended practices.
Hm, you're changing your tone here; before you said tutorials were enough. :)
As for getting this done I see this general procedure:
1. identifying areas that need recommendations
I hope I offered some help there. Again, reviewing code will help with this identification process. I can't do it, as I don't have a clear idea yet on what my code _should_ be like, regarding Zope.
2. proposing recommendations 3. reviewing recommendations 4. blessing recommendations
I think much of this work can be accomplished on the Zope-dev list with Zope community members and DC folks working together. (I think of these as Zope community recommended practices, not DC recommended practices.)
Yes, it should be a product of a community process.
I personally would be most interested in working on step 3. BTW, when recommendations get to the blessing stage we may want to revise Zope itself to follow the recommendation.
I think this process of generating recommendations could be helped immensely if we looked at each other's product code. Regards, Martijn