[Zope-PTK] Zope Documentation Portal

[Maik Roeder]

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)
  nickname: Subject

  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)
  nickname: Topic

  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)
  nickname: Recipient

  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
  login name.

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
using ZCatalog:

   DocumentFolder
      Subject
      Topic
      Recipient

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):
    subject: Zope
    topic: ZDP

Let's look at an example of how the subject/topic hierarchy is
interwoven in the document hierarchy:

  * Root (nickname: ZDP: Zope Documentation Project)
    subject: Zope
    topic: ZDP

    * Project Folder (nickname: Projects)
      subject: ZDP
      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)
     subject: ZDP
     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
parent (ProjectFolder).

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
document hierarchy.


Greetings,

Maik Röder

-- 
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/