Feature Proposal: Clean up the parentage of topics shipped with Foswiki

Motivation

Navigation mechanisms based on topic hierarchy (that is, users browse their topics by topic parent hierarchy) expose Foswiki's extremely poor usage of parent meta in its distributed topics.

Users appreciate being able to arrange their topics into logical hierarchies - it vaguely resembles the folders concept they're familiar with from operating systems.

SvenDowideit has already gone some way towards cleaning up parentage of topics shipped with the core distribution, but the situation with non-core plugins in the System web can only realistically be cured by automating it in BuildContrib.

Also, particularly with new webs given to new users, the 13 (thirteen!) Web* topics which all exist at the root of the _default web completely drown out the user created topics, especially if the user has organised all of their own topics under only a half dozen or less root topics of their own.

Many users are extremely bothered by clutter and are actually put off from participating in the wiki.

Description and Documentation

Two tasks have been created to tackle this problem.

Web* Topics (Tasks.Item2293)

This task concerns the parentage of the Web* topics in the _default and standard System, Main, Sandbox webs. The proposal so far:

• WebHome
  • WebTopics Changed 10/11/2009
    • WebSearch
      • WebSearchAdvanced
    • WebChanges
      • WebNotify
      • WebAtom
      • WebRss
    • WebStatistics
    • WebIndex (? these ...
    • WebTopicList ... two need rethinking ?)
    • WebPreferences
    • WebCreateNewTopic
    • WebLeftBar

The placeholder topic (WebTopics) should be a "dashboard" area that should present the range of functions available to the user in a logical manner. This might mean re-thinking the content and purpose of some of our existing topics (Eg. WebIndex vs WebTopicList). For 1.1, I think it is reasonable to kill/rename/re-purpose some of these topics. But I would like to apply some sort of solution for 1.0.x as well. -- Main.PaulHarvey - 10 Nov 2009

BuildContrib should automatically set topic parents (Tasks.Item2336)

This task concerns part of the mess as it pertains to Plugins, Contribs and Add-Ons (-- PaulHarvey - 10 Nov 2009) that exists in the System web

Implementation

BuildContrib should call a new tool, /tools/autoparent, which it would apply to all topics shipped in Contribs, Plugins and Add-Ons.

/tools/autoparent would also be useful for deployment of hierarchies to existing webs, such as the proposed hierarchy of Web* topics in Tasks.Item2293. -- PaulHarvey - 10 Nov 2009

Plugins

These rules would apply within any web where the rules are being applied (all webs containing topics shipped with a plugin).

• System.Plugins should be the parent of ThePlugin topic .
• !ThePlugin topic should be the ancestor of AllOtherPluginTopics:
  • So topics that were descendants of a topic that has now been automatically parented to ThePlugin topic should not be modified.
  • Any topic after the !noautoparent directive in the MANIFEST file should not be auto parented

Contribs & Add-ons

Same policy as for Plugins

Example

• Plugins
  • ThePlugin
    • ThePluginFAQ
    • ThePluginCookbook
    • ThePluginExamples
    • ThePluginSimpleExample Changed -- Main.PaulHarvey - 10 Nov 2009
    • ThePluginBigExample Changed -- Main.PaulHarvey - 10 Nov 2009
    • SomeForm
      • SomeViewTemplate
      • SomeEditTemplate
      • SomeTemplateTopic

It's not necessary for BuildContrib to enforce a complex hierarchy. The only things it should do:

1. Ensure that the ThePlugin topic is parented to Plugins
2. Other topics shipped with the plugin are descendants of ThePlugin topic...
3. ... except for topics below !noautoparent in the MANIFEST

-- Main.PaulHarvey - 10 Nov 2009

Exclusions

As with !noci, there should be a directive in the MANIFEST that allows prevention of autoparenting when building a release.

Proposal: !noautoparent

Examples

Impact

WhatDoesItAffect:

%WHATDOESITAFFECT%

edit

Implementation

-- Contributors: PaulHarvey - 07 Nov 2009

Discussion

I like this proposal a lot. I had the same problems back then when I introduced TWiki in my former company.

Is "ThisWeb" meant as a placeholder? If so, for what? If not, it is not self explanatory.

Why not use something more meaningful like "SystemTopics"?

• WebHome
• SystemTopics
  • WebSearch
    • WebSearchAdvanced
  • WebChanges
    • WebNotify
    • WebAtom
    • WebRss
  • WebStatistics
  • WebIndex (? these ...
  • WebTopicList ... two need rethinking ?)
  • WebPreferences
  • WebCreateNewTopic
  • WebLeftBar

-- CarloSchulz - 09 Nov 2009

Basically, the parentage does not really fit a real taxonomy or categorization system.

The reasons are manifold. Even breadcrumbs are no good indication where in a taxonomy a topic is located. That's because a topic might need to be filed into several categories at the same time. E.g. a WebTagCloud topic that is part of a plugin. Where does it go: under SystemTopics or under the plugin's own subtree. It belongs to both. Impossible to model using parentage as we don't allow multiple parent topics in Foswiki. In fact, assigning a parent topic could even obfuscate the affiliation of the topic. In a real taxonomy things like number of root-level nodes, (artificial) inner nodes, tree depth etc matters a lot to create structure that still remains manageable by users navigating among content as well as authors creating new content in the first place.

However, I agree that the current category system in the System web isn't a good replacement either. But going into the right direction.

I think reworking the complete information structure of the System documentation, tools and whatever is cramped into it is needed instead of going for fixing parentage alone.

Sorry for painting bit black

-- MichaelDaum - 09 Nov 2009

em, so what do you propose concerning this proposal?

-- CarloSchulz - 09 Nov 2009

The System web needs a thorough refactoring before going for breadcrumbs.

-- MichaelDaum - 09 Nov 2009

Web* topics

I forgot to mention that I would like the "placeholder" topic to be a sort of dashboard for the web in question. So it should present a logical arrangement of features relevant to the web in question to users (as much as "logical" is possible).

I suppose the only reason I chose "WebThis" is that some wiki apps exclude topics named Web*. But as I've not been doing this (tm)wiki/Foswiki thing for all that long compared to the rest of us here, maybe I've attached too much importance on our WebTopic naming scheme?

I'm not sure I like SystemTopics, as it sort of confuses it with the System web.

How about WebTopics?

System topics

I believe MichaelDaum's concerns are:

• The content of our System topics needs some work, before we can begin to think about applying a simplistic hierarchy. I would agree.
• Topic parents are too limiting. We should be moving to other ways of categorising topics: such as tagging (and hierarchical tagging - ability to tag other tags, so that you might browse the "tag space" before deciding to see the resulting set of topics). I would agree.

Actually, thanks to DBRECURSE and DirectedGraphPlugin, I am having lots of fun with some users in creating interesting, many-to-many multiple-typed relationships between topics.

TOPICPARENT is here to stay for a long time to come however, and I suspect that its application to topics shipped with core, plugins, contribs and add-ons could be substantially improved without any detriment.

This is what I am proposing: cleaning up topic parents.

I know that categorisation of topics is a larger, very important problem which does need to be solved, but my concern for now is simply improving application of an existing feature.

I suspect some readers of this proposal may not understand my urgency in solving this, and that's probably because you've only used topic parents for generating breadcrumbs

-- PaulHarvey - 10 Nov 2009

MichaelDaum, do you have a specific objection to Tasks.Item2336 or Tasks.Item2293?

I have deliberately kept the scope of this proposal to a minimum:

• So that it's not intrusive and does not break anything.
• Because it represents the best I can do with the time I can justify for this effort.

SvenDowideit raised a good point about the Web* topics situation, and that is that Foswiki should be provide the means to make "phantom topics" - it would be much better if we didn't actually populate every web with Web* topics, and instead an attempt to access such a topic would actually fall back to something else defined in just one place.

-- PaulHarvey - 10 Nov 2009

Maybe it's a bit too bureaucratic but the dashboard idea (especially it's design and contents) might be another proposal? I don't know...

-- CarloSchulz - 10 Nov 2009

Wasn't aware that BuildContrib is under consideration here. Let's see what it breaks

I know that your work is mainly cleaning up topic parents. Well if you have the time, go for it.

My objection against your current approach is that topics like WebTopics are not well thought out. The rest of the content needs "reparenting" as well. Note also that topics like WebTopics (being the root for all "!WebTools" <- better name) significantly interferes with the half-backed categories that we have currently in the System web. As I see it the approach followed here must inevitably deal with the XXXCategory topics that are already there which are:

• AdminDocumentationCategory
• AdminToolsCategory
• CategoryCategory
• DeveloperDocumentationCategory
• UserDocumentationCategory
• UserToolsCategory

The last category is most similar in purpose to your WebTopics.

This directly leads to my main concern I raised before: best would be to wipe out all XXXCategory topics and create a taxonomy that fits best the content in the System web. One category will probably become the parent topic for what you called WebTopics for now.

Apropos dashboard: the main "dashboard" of a web is of course the WebHome topic.

So please try to see the System web as a whole and don't treat each topic in isolation. That won't clean up the mess.

-- MichaelDaum - 10 Nov 2009

WebHome is a dashboard, but not the dashboard which I would hope the WebTools topic to be (a better choice I will admit, but to me it didn't really fit WebPreferences or WebLeftBar, but that's probably because I was thinking too hard at the time).

Half the time, the first thing that users seem to kill on their shiny new TheirOwnWeb is the "junk" at the bottom, partially because most of it is accessible in other ways through the site skin and partially because they want their users (on publicly viewable webs anyway) to not be distracted from the content.

• I totally agree -- MD

I fail to understand how topic parents will break *Category system though. Can you elaborate? Do you mean that we will have two competing taxonomies? I was hoping that they could actually complement each other (certainly it's nice to be able to flatten hierarchies sometimes, which the *Category topics "system" kind of does, however unsatisfying it may be).

• Right, they are connected. Sorry if I did not elaborate that before. In a taxonomy child nodes ideally indicate their location using the breadcrumbs ... obviously only works for topics and categories being only in one category. That's why we have to deal with those categories and the content they span at the same time unfortunately. -- MD

My main concern with the System web is all the plugins and contribs are "polluting" the top-level by not consistently applying the parenting convention that some plugin authors seem to have agreed on. Getting BuildContrib into the equation would formalise and enforce that convention into a policy.

• Ya I see. Well, then lets first outline a complete taxonomy before ending up reworking this all again and again under different proposals. -- MD

It doesn't solve the arrangement of System documentation, but I don't intend to solve that problem in either of the two tasks that I created.

• That's why I raised concerns -- MD

MichaelDaum, may I assume that you would remove yourself from ConcernRaisedBy if:

1. Proposal was complete with spec for System topics hierarchy
2. We solve the Web* topic situation by discussing and developing this WebTools topic further

-- PaulHarvey - 10 Nov 2009

Btw found this link about Create a Single Navigation Hierarchy for Your Entire Site ...(using parent-child relations among topics).

-- MichaelDaum - 10 Nov 2009

I think we try to solve too many problems here.

There is the _default web where I think the WebTopics or WebTools dashboard topic would be a good creation. This way I can put a single link on WebHome and have all the Web* topics on that. I would not want WebChanges to be parent for WebNotify. We do not need that 3rd level. Just all the topics flat under WebTopics would be fine.

And with this tool topic organised as simple topic with headlines and bullets.

For System web. The parent system that was introduced recently is not good for breadcrumb. I have seen parents with CategoryCategory. Geek talk. And not user friendly navigation in the breadcrumb context.

Let is think of something very different in System web and only address the parent/child in the context of the topics that are common to all webs.

-- KennethLavrsen - 22 Feb 2010

I agree that additional nesting in the path breadcrumbs does not add any value.

After I rewrite my ajax topic browser tool (which works via breadcrumbs + topic hierarchy), and release it, then there will be some value to working on this proposal.

-- PaulHarvey - 23 Feb 2010

Here's something totally unrelated: Parenting In Post 2.0

-- MichaelDaum - 23 Feb 2010

Although I intend to revisit this one day, I lack the time to do so, at least for the next release.

-- PaulHarvey - 07 Mar 2010

Commenting is disabled while not logged in