[Zope3-dev] Development methodology (Re: [Zope-CMF] Future CMF) (rant)

[R. David Murray]

On Wed, 9 Oct 2002, Chris Withers wrote:
> Probably the main reason I've made no real Zop 3 contributions of late is that
> it's too difficult to get into. I think this is due to lack of documentation.

I agree, and I'm (slowly) working on that problem.

> That said, I'm not sure long and convoluted proposals (which I never have time
> to read properly ;-) help either.

But they help more than not having them would.  I couldn't find *any*
proposal docs or wiki pages relating to the configuration system,
for example, so I had to read the code to find out enough about how
it worked to write some docs.  If I'd have had a proposal to start
from, I think the learning curve would have been a lot shorter, even
if the final code deviated non-trivially from the original proposal.

> What I really need is a 'beginners guide for potential developers' showing me
> the overall shape of the thing so I know where to best pitch in.

I want one too.  I wouldn't recommend you hold your breath until
I manage to write it, but at least it's on my radar screen these days.

> It's be nice if I knew where and how to document Zope 3 too. Maybe we need a CMS
> for that? Dogfood eating anyone? (Just as long as it doesn't end up like
> cmf.zope.org, please god!)

I'm not at all sure I want a CMS for that.  I think this is a
discussion it is time to have (again).  Right now I like seeing the
"official" documentation (ie: not the proposals, but docs about how
things really work right now) in the cvs in stx format.  I wouldn't
object to having an "official book" like the Zope Book, but I don't
think we have enough of an information framework to *write* that
book for Zope3 yet.  So what I want to do right now is document
stuff as I understand it in pieces (components?  <grin>).  And I'd
rather store that in the CVS than on the Web; the web just feels
too squishy for that to me <grin>.  The other advantage of CVS is
that one can check in changes to the docs when one checks in changes
to the code, and thus the two are more likely (I think) to stay in
sync.

You know, that brings up a question.  I'd *actually* like to move
my meta configuration guide into the Zope/Configuration directory
where it will be "right next to" the code it documents, leaving a
pointer in the doc/zcml directory.  What do people think of that
notion?

--RDM

PS: doc/zcml/namespaces.zope.org is somewhat out of date with respect
to the code.  That's the problem I am currently working on.