[ZDP] On possible implementations of topic, subtopic, category and keyword in ZDP ZDP

Maik Roeder roeder@berg.net
Sat, 11 Mar 2000 19:40:35 +0100


Hi !


I will try to put together all that has been discussed 
on the ZDP mailing list about keywords and categories.

Quote from the Zope Documentation Plan by Amos:

"Tips and How-Tos could be organized in a better fashion,
perhaps using Topics."
http://www.zope.org/Members/Amos/Documentation/Plan

------------------------------------------------------

A problem with the present doc is finding the relevant
information. Lots of docs are already available but you
have to browse a lot to find the information. Even if
we have categories and keywords, chances are that the
answer you are looking for is not in any topic you might
think of when you have the question !

-----------------------------------------------------

The solution has to be well thought out, because once
implemented it will be _very_ difficult to change.

------------------------------------------------------

First we may have to agree on what we mean by the words
topic, subtopic, category and keyword:
               
               level |  specifity | example
---------------------+------------+---------------
1. Topics      high  |  low       | Python
2. Sub topic         |            | XML
3. Category          |            | Parser
4. Keyword     low   |  high      | pyexpat
---------------------+------------+---------------
5. Full text   lowest|  very high | parse_xml

Then we have to decide who is going to have the right to
change these:

1. controlled lists
   keywords and categories are fixed
2. uncontrolled lists
   The problems with these lists are that everyone
   is going to put in their own aberrations, which make
   the result, um, less than useful.
3. reviewed lists
   new keywords are reviewed first by a maintainer

-----------------------------------------------------------------

Levels of access in Presenter cases:

1. Per Topic            + full text search in Topic only
2. Per Sub topic        + full text search in Sub topic only
3. Per Category         + full text search in Category only
4. Per Keyword          + full text search on keyword only
5. Per full text search in all resources

------------------------------------------------------------------

Use Cases:

1. Use Case: Visitor Search

The visitor can chose his level by searching from a certain Level.
For example, the visitor knows that the Category should be
Python -> XML -> Parser
He now performs a search within this topic.

2. Use Case: Display FAQ-Questions sorted by category

The FAQ Questions in a FAQ Section are ordered by Category.
If the FAQ Section can compare to a Sub-Topic, and the 
visitor wishes to see all Categories in 
Python -> XML -> Parser
He is presented the FAQ-Questions by Category

3. Use Case: Display Snippets sorted by category

There are many Snippets in one SnippetFolder, and it would make
sense to order the Snippets contained in them by a certain
category.

4. Use Case: "What's related" search

A visitor may have found a resource in the ZDP which answers
some of his questions. He would like to further explore ZDP,
but instead of searching directly, which most people would
do, he makes a search for what's related. This search is
performed using keywords.

5. Use Case: "More about" search 

A visitor has found a good resource on ZCatalog. He now wants
a list of all other resources which have the same category/topic.

The "What's related" and "More about" searches could be made
a standard 'builtin' hyperlink feature, as Tom has proposed.

6. Use Case: Add FAQ Question with existing keywords

The user wants to add a FAQ Question. He has the possibility to add
some keywords to them. 

7. Use Case: Add FAQ Question with new keywords

The user is not satisfied with the existing keywords and wants
to add his own. To do this, he first has to go to the Keywords
Folder, and enter the new keywords there. Then he has to go 
back and add the keywords to the Question he originally wanted
to post.
Alternative: The user just enters the new keywords, which are
automatically added to the Keyword Folder.

9. Use Case: View meta book

To generate our meta-book, we need to :
- Iterate over the TopicFolders and their Categories;
- Sort them based on their Order property;
- Use their UniqueID property to retrieve matching
  objects from the catalog.

Categories could also be used to provide "See also" links
in a FAQ Section for instance.

10. Use case: generate list of all resources for a specific topic

This  would create a kind of "road map" or "resource finder"
for Zope, which would be great to have ! It is badly need,
because new users are overwhelmed.

-------------------------------------------------------------------

Implementation:

It would be possible to implement this by storing topics, subtopics,
categories and keywords as folder and subfolder instances of
respective ZClasses.

topics, subtopics, categories and keywords have a unique id.

To assign Topics or Categories to ZClass items (eg. FAQ Questions),
you  pick them in a selection list. The selection list displays
the Topics text. Internally it contains the Topics/Categories unique ID:

<SELECT name="selected_topics:lines" multiple size="10">
  <OPTION value="98765798543">Creating ZClasses</OPTION>
  ...
</SELECT>

When you OK a selection one or more unique IDs are stored as lines in
the selected_topics property.

The selected_topics property is indexed in the catalog.

There could be a global registry or local registries for topics,
subtopics, categories and keywords.

Is the following ok ?

Topic:     -  Python
SubTopic:     - Zope
Topic:     -  Zope
SubTopic:     - DTML
Category:       - syntax
Category:       - variables
Category:       - tags
Category:     - Security
Keyword:        - roles
                - permissions
                - passwords
                - authenticated_user
Category:     - external methods
Category:     - python methods
Category:     - argument passing
Category:     - content manipulation
Category:     - python products
Category:     - acquisition 
Category:     - zsqlmethods

Presentation possibilities to make make browsing as easy as possible.

1. links to related items
2. on base on a catalog per category sorted on keyword
3. with a tree to subsections (alphabetic order, another order?????)

Implementation with Catalog

A catalog based approach to all of this would probably be very
attractive. In this way information could appear in more than one
category without duplication.



Greetings,

Maik Röder