[Zope-PTK] Zope Documentation Portal Community Policy

[Maik Röder]

Hi !

[Rik:]
> However, taking into account the discussions about the Portal Toolkit
> and documentation of the last few days, I have another proposal. Let's
> make it an official Zope Community Policy (TM) to make all documentation
> primarily available through the new Documentation Portal. 

I think we should steer in this direction, but the first rule is Linus's motto
of "Show me the code", and then we can talk about moving the whole process of
Documentation to ZDP if all parties agree an this.

I would like to develop this system like a prototype at first, and if it
works, we can approach the Zope community and Digital Creations to ask them
to make the documentation available via ZDP only.

> And, to get personal ;-), this would also mean that DC makes a commitment
> to do so. In this way we'd create the necessary clarity in Zope documentation. 

It would be great if DC would collaborate more with the ZDP, but as long
as this is not the case, we can only do the second best thing, and provide
a solution that just links to what is available on zope.org. It would
be a big improvement even if noone collaborated, but let's not get too
pessimistic ;-) 

>In other words, more than a change of policy in the ZDP, let's make the
>Documentation Portal thing for and of the whole Zope Community.

Agreed.

[Chris Withers:]
>How do we know what documentation applies to what Zope version?

We have been talking about this, but we have not yet come to a solution.
I don't think it would be great to add a version property to all
documents. Instead, I would like to store the creation date explicitely
and infer the Zope version from it.

>What's the difference between the above and documentation that has been
>corrected/abandoned because it was simply wrong/out of date and not just wrong
>for a version of Zope? 

Wrong documentation can appear in the best content management system. As
long as peer review does not take place bad documentation remains bad.
We are planning a system where a Reviewer can select outdated stuff which
will stay there for a while and be removed by an Approver perhaps after
checking back with the Maintainer.

[Tom:]
> Nice idea, it looks something to the small knowledge base I've made.

If I understand you right, the following ZClasses are
the same in your KB and in the ZD Portal:

TopicFolder = TKBCategory
Topic       = TKBItem

TKBCategory objects contain a string of the categories in which they exists
TKBCategory objects contain TKBItem objects. The KBItems contain nothing.
A ZCatalog searches for the TKBCategory objects 'category' property.
A search for the category leads to the TKBItems by going to the TKBCategory
Folders and listing all it's items ?

> Generally I think it is a good idea to create the ZDPortal. However, I hope
> the way to generate the hierarchy wouldn't be too difficult or to
> slumbercome.

The hierarchy is created on the fly while adding documents. The subject of
every object is always the topic of the parent. Therefore you only have
to specify a Topic. There are as many Topics to choose from as there are 
Topics in the Subject it is created under. If the Subject or Topic does not
yet exist, it can be created dynamically, successively building up a hierarchy.
This process can be moderated.

[Kamon:]
> It would be good if PTK and ZDP-Tools efforts could join to agree on common 
> API's.

Right, can someone from the PTK mailing list comment on this ?

Greetings,

Maik Röder