[ZDP] Re: [Zope] The agony of the ZOPE Documentation

[Chris Withers]

Hi Ethan :-)

mindlace wrote:
> You got it.  I think that the ZD portal and Zope.org should be
> seamlessly integrated.  More to the point, I have the authority to make
> it happen on DC's end.  I am *very* interested in integrating the
> community's effort more completely into Zope.org.

I reckon there should be only one, and no, I'm not Highlander ;-)

> So I *do* have time to help with this, and I don't imagine my employer
> will give me flack :)

Excellent :-) It's about time...

My views...

Zope.org is very out of date now. I think ZDP is actually closer to what
Zope.org should be, but the implementaion sucks.

What 'The Zope Portal' should have:

-Members section/portal, as it currently is.

-Products section/portal, as it is. how do we integrate docs from these?

-The new portals from the ZDP (these are pretty much correct, I think)
so people can get to all the stuff relevant to them (particularly
newbies) quickly and easily.

-A 'Reference' section containing ZBook and ZQR. This would also need a
new DTML reference, and an API Reference. This is for people who know
what they're looking for and just want to check/find details. All these
references should be stored in small chunks, though, so they can be
extensively referenced from elsewhere (like in the portal...)

The key for this is the development of decent documentation tools,
kindof ZDP-Tools++ ;-)

My mini-brain-dump on this:

I would structure it around the idea of a commentable paragraph object,
which has an owner who is responsible for it. You then need a
chapter-like folder object to contain these paragraphs, in order. They
should also have a responsible owner. You need to cater for different
versions of paragraphs, which provide the correct information depending
on what version of zope you're using. Attached to paragraph or chapter
objects you may have links, relevant searches, etc.

Much of the above has already been done by the ZDP, it just needs to be
bug-checked and have the interface sorted out. The current interface is
very much oriented towards writing docs. I think we need an
_alternative_ interface for browsing...

The other very important thing which needs doing is to get the overall
structure of the folder objects (ie the chapter headings and stuff)
right from the start so people can browse to where they should be
looking and then, if there's no docs there, write them :-)

I liked this a lot...
> It might be better if all information were contained in all portals,
> but organized differently.

I agree with Maik, we now have all the players at the same table, so
lets get this card game going so we can all be winners :-)

cheers,

Chris

PS: What would you (Ethan) see as the uses for zope.com, zope.org and
zope.net respectively? 

PPS: Maybe the ZDP Wiki could be re-purposed for coming up with the
structure for 'The Zope Portal' (TZP?)