[Zope-PTK] Zope Documentation Portal
Fri, 28 Apr 2000 10:49:27 +0200
Hi everyone !
I suggest changing the Zope Documentation Project to a
Zope Documentation Portal. This Portal would integrate a view
on the existing ZDP content and Zope.org content by creating
links to Zope.org documents and enrich these links with
meta-information. So even though not all documentation is
stored in one place, there can be one place from where all
documentation can be reached conveniently.
To make Zope documentation available under certain subjects and topics
for different users, a new Portal ZClass is needed that provides
different views on the Information Space. The following is a
suggestion for implementation of the new Subject/Topic Hierarchy.
David Kankiewicz has already worked on this problem, and also
implemented part of it on the ZDP site. Nevertheless, I want
to throw in my thoughts on this, which came up as I tried to
understand Davids code ;-) The PTK project also works on this
problem, so I have CC'd this mail also to this list to exchange
some ideas. In the long term the ZDP-project needs to adopt
the PTK, and so discussing this early on could be beneficial.
Create three new ZClasses:
* TopicFolder (derived from DocumentFolder)
In the root folder, there should be multiple TopicFolders for
each Subject. Subjects can be for example "DTML" and "Web Server".
Anyone can create TopicFolders, but unless they are approved, it
is not going to be publicly visible.
* Topic (derived from Search)
Under the TopicFolders, which define the Subjects, there should
be multiple Topics. Topics will find their contents through
a ZCatalog Search and so it makes sense to derive it from the
Search ZClass which already exists in the ZDP-Tools. As with
TopicFolders, they can be created by anyone, but must be
approved to get visible.
* Portal (derived from DocumentFolder)
Portals filter the TopicFolders and Topics for interest groups,
defined by the Recipient nickname. A Portal can show the TopicFolders
with their abstract or show the TopicFolders with their Topics
as links in a Yahoo style. Portals are only added by Managers with
one exception. Portals may also be used to create a Personalized
view on the information space for members. Members may want to
put their own Portal(s) into their MemberClass. The Recipient variable
would in this case just be user defined, and default to the member
When the Subject/Topic hierarchy is built, then it can be displayed
very fast inside a Portal without using ZCatalog. The ZCatalog search
starts inside the Topics for the first time. When a Topic is displayed,
a Search is performed with the following parameters:
* Subject = TopicFolder.nickname
* Topic = Topic.nickname
* Recipient = Portal.nickname
This should keep the number of results rather small. We are already
deep in a context and filter on the Recipient. This could be further
reduced by introducing new filters like for example "zen_level".
So, as a consequence we have to give every ZClass the following
properties so we can search on them in the document hierarchy
Now, let's see how document creation would look like. When we create
a document, we are always somewhere in the document hierarchy, and
can always assume that we are in the context of a subject and a topic.
This can be solved by making the following subject and topic default:
Root (/ of zdp.zope.org):
Let's look at an example of how the subject/topic hierarchy is
interwoven in the document hierarchy:
* Root (nickname: ZDP: Zope Documentation Project)
* Project Folder (nickname: Projects)
topic: ZDP projects
* Project (nickname: ZDP-Tools)
subject: ZDP projects
topic: ZDP-Tools project
* ProductDocumentation (nickname: Documentation)
subject: ZDP-Tools project
topic: ZDP-Tools Documentation
Please notice that the subjects are always the topics of
the parent folder.
To see where we take the subjects and topics from when
adding a new document to the document hierarchy, we have
a look at an example:
Let's suppose we want to add a new Project called ZBook to the
document hierarchy under the Project Folder:
* ProjectFolder (nickname Projects)
topic: ZDP projects
* Project (nickname: ZBook)
subject: ZDP projects
topic: ZBook project
When the Project is created, the subject is already predefined.
The subject is defined as the topic "ZDP Projects" of the
In the Subject/Topic hierarchy the Subject "ZDP projects" already
exists if there have been other projects defined earlier. In this
case we only have to care for a new TopicFolder with the nickname
"ZBook project". Someone who is allowed to add a Project should
also have the right to add TopicFolders.
If the Subject "ZDP projects" does not exist as a Subject, but only
as a Topic of the ZDP TopicFolder, then the Subject "ZDP projects"
would have to be created in a TopicFolder, and inside of it, a
Topic of "ZBook project".
The Subject/Topic hierarchy should break once we get too specialized.
For example it may not make sense to give new Topics and Subjects to
Comments that are also reflected in the Subject/Topic Hierarchy.
The subjects and topics can perhaps still be there in the Documents,
but they won't mess up the Subject/Topic hierarchy which needs to
be kept small and clean, but could even so be kept small by filtering.
Generally, we never choose Subject and Topic together because
in the Document Hierarchy we build on the principle of containment,
and we have no content flying around in mid-air. When you create
a document in the document hierarchy you always get the subject
for free from the topic of the partent folder. The Topics
can be naturally fed from the Topics in a TopicFolder with the
name of the subject when they exist. The Topics would be selectable
in a selection list at the time we create a new document in the
Open Source is "about being able to work together with people you've
never met, on projects that are in a constant state of flux, on
a time schedule that would cause a hummingbird's head to spin."
Paul Ferris, http://www.linuxplanet.com/linuxplanet/opinions/1593/1/