I'll collect some thoughts here on enhancements for Tiki. In the interests of exposing potential bias, I am a Tiki admin, fairly new to Tiki but mightily impressed by what it can do already. So in some ways, I am offering advice to angels here.

My goal is to set down some thoughts for feedback from others, and depending on the feedback, to form the basis for RFEs.

Table of contents

Help system

I doubt that anyone would claim that Tiki's end user Help system/documentation is a strong point of the product. This page is intended to provide an overview of weaknesses and plausible solutions.

  • The fundamental problem is that the Tikiwiki end user Help system has evolved in a somewhat helter skelter fashion as a result of incremental improvements without a long-term development roadmap that addresses the Help system's development systematically and identifies achievable milestones.

Definitions

  • Context-sensitive Help means those Help pages invoked by clicking on the tiny blue question mark icons with Tiki 1.9.2 as the reference version. These Help pages are mapped to a single server through a text field setting under Tiki -> Admin -> Administration: General.
  • Help system as used herein means the totality of Tikiwiki end user documentation, viewed as a system.

Comprehensive Help system review and overhaul using a systems approach are needed

End user input

  • A series of incremental changes could better encourage end users to submit Help system bug reports/FREs, as well as encourage a much larger user-to-user support community.

Problem description

  • The Tikiwiki product and supporting web sites are not designed to encourage end user Help system feedback for documentation developers.
  • Many needed elements are already in place but need to be brought to end user attention.

Help system bug reports and FREs

Context-sensitive Help

Problems addressed

Problem 1 --- Inadequate context-sensitive Help server mapping

Problem description
  • Tiki documentation will never be stable; it will always be a work in progress.
  • Tiki Admin -> Feature settings currently allow mapping of context-sensitive Help only to a single server.
  • Mapping to d.tw.o. Because documentation on doc.tiki.org is incomplete, if Tiki Help is mapped to that site, many context-sensitive links produce d.tw.o pages that are empty of content.
  • Mapping Help to www.tiki.org does not provide the most up to date documentation for some issues that are better covered at d.tw.o or that are not covered at all on www.tiki.org or do not reflect code revisions in later versions of Tiki.
  • Result is a Hobbesian choice for Tiki users. Either way, you don't get the most appropriate documentation.
  • Tikiwiki loses points every time an end user invokes context sensitive Help and does not receive useful information.
  • No good workaround. (Three possible work-arounds discussed below.)

Problem 2 --- No easy solution for Tiki users who wish to customize Tiki context-sensitive Help.

Problem description.
  • Tiki administrators who wish to customize Tiki context-sensitive Help pages for their end users have no easy means to do so.

Problem 3 --- Similar issues for Tiki users who wish to use Tiki as a documentation server.

  • Wikis are an excellent choice for documentation projects that never end, providing that we can work past issues such as these.
Problem description
  • Consider the barriers faced by a software project that wishes to include Tiki as one of many integrated applications in a Linux distribution, using Tiki as the documentation server for the distribution. This is a real life issue my project is facing.
  • We will stand in the same position as to our end users as Tikiwiki.org stands in regard to our web site Tiki. Tiki does not provide a good facility for serving continually updated documentation to our end users.

Workarounds

Option 1: server level URL redirection.

  • Tiki administrators can ask their sysadmins to establish server level URL redirection to their preferred pages for each Tiki context-sensitive Help page.
  • Not a good solution for reasons including:
    1. requires repeated duplication of efforts by all Tiki users who want to stay up to date;
    2. would require each Tiki admin to constantly review d.tw.o to determine which previously empty pages now have adequate content;
    3. Tiki admins may not be competent to evaluate the adequacy of documentation without detailed comparison of documentation with features they may not use extensively themselves; and
    4. on many sites, repeated requests for sysadmins to redirect URLs could result in friction and/or delays.

Option 2: Mapping Help to the local Tiki

  • Tiki administrators can map to their own Tiki and create referral pages with names that duplicate those page names required by the Tiki context-sensitive Help system, and on each of those pages put:
    1. a link to the tw.o or d.tw.o page that has the best documentation for the given issue.
    2. a supplemental link to the other tikiwiki.org page.
    3. link(s) to other local or external page(s) that provide supplemental documentation for the given issue.
  • Enables local supplementary documentation for given issue, such as recommended workarounds for specific issues, more tutorial approach, links to appropriate FAQs, etc.
  • Gets past the server-mapping barrier, but:
    1. requires duplicated effort for every Tiki installation
    2. Tiki admins still have to review tikiwiki.org documentation pages individually to determine what should be linked.
    3. Tiki admins have to do a fair amount of work to make this happen, translating into it not happening very often. Tikiwiki still loses points every time an end user winds up staring at an empty page after invoking context-sensitive Help.

Option 3: Importing Tiki Help pages to local Tiki

  • A variation on workaround 2, except that the Tiki admin imports the documentation pages from the tikiwiki.org Tiki of choice and annotates it with supplemental local documentation.
  • Eliminates the need for end users to select from links on intervening local referral pages, but:
    1. Requires periodic monitoring of tikiwiki.org pages to ensure that updated information is migrated to the local counterpart pages.
    2. No easily scriptable solution.

Other workarounds?

Interim solutions

Option A: Server level redirection of incoming page requests received by d.tw.o. for relevant pages at tw.o.

  • The heading says it all.
  • The heading says it all.
  • Maybe add a "why don't you write it for us" link.


Editing in progress