STATUS: Firming up planning, accumulating designs and mockup images

Contributors: Nmonk, DuncanLithgow

This is a master spec for several related topics, and is currently in an early state of development. Please feel free to contribute anything that comes to mind.


The goal of this spec is to explore ways of closing the gaps between various types of help, cross-breeding their respective strengths and centralizing the information.


I selected the wiki system as the central point of reference because by its flexible and visible nature it is CAPABLE of connecting to all systems, but it is equally true that all the other systems benefit by connecting where they can.

Hypothetical Release Notes

The installed help utility is now integrated with online help resources, seamlessly referring users to additional resources and allowing caching of updated bugs, tips, and howtos for the currently installed versions of all programs.

The online help pages now link directly to appropriate chat, forums, and external information.


When someone needs help, having all the help systems in one clear and easy to use location is much better than having to search dozens of sites, miss dozens of others and hope the information you find is accurate. By enhancing the wiki system to connect to as many support systems as possible, you drive most activity to the same point, thus keeping that point fresh and polished.

With the wiki system receiving much more activity, it's information is ever riper for the offline docs to leverage. The docteam can kill two birds with one stone by managing the core structure of the wiki. When they organize and approve essential sections of the wiki for offline caching, their managed sections automatically provide the live wiki with a sturdy skeleton on which to grow more user-tended content, and good user-rated feedback systems keep even the most tightly managed sections fresh.

When you connect all the systems together, you also have an opportunity to homogenize the interfaces. That way people who learn to use the most basic help features find a smooth transition to using others, and are more likely to wind up helping solve the problems of later users (intentionally and incidentally).

Use Cases

Bob is having trouble using a program. He checks the installed help and cannot find the answer to his problem. However, he does find a link suggesting he check for more information online, which connects him to...

... the official Ubuntu wiki page for that program. Most of it is what he just read on his PC, but it also contains some interesting Howto's (that sadly do not cover his issue) and links to the official web page for the software...

... which gives him a better understanding of the issue, but not quite enough information to solve it. When he returns to the wiki to check for more info he notices that another user has added a comment to the section he is having trouble with. They are having the same trouble he is! He adds his experiences to theirs ...

... and then goes to the chat section at the top of the page to see who else might be having the same problem in #ubuntu-somecategory. Connecting immediately on the page, he finds a person who ran into the same problem last week, and another who is having it now...

... and finally finds all the pieces he needs to fix the problem. He returns to the official ubuntu wiki page for that software and makes a suggestion to update the page so other users can avoid the same problem. Other users who run into the same problem find and promote his suggestion, making it obvious to ...

... the editors of the page, who can quickly incorporate it into the body of the page for all users to see online and eventually (see beginning) in their installed help.


Design Images + Implementation Sub-Specs

Installed + Online

Spec: LinkingDesktopToOnlineHelp

Status: Design and Brainstorming to update existing spec

3 picture essay:

Notes to push to spec:

Internal + External

Spec: ExternalLinksRedirects

Status: Add to existing draft

3 picture essay:

Wiki + IRC

Spec: ConnectingWikiToChat

Status: Design and Brainstorming

3 picture essay:

Wiki + Forums

Spec: ConnectingWikiToForums

Status: Design and Brainstorming

3 picture essay:

Fresh + Managed

Spec: ConnectingSuggestionsToManagedPages

Status: Design and Brainstorming

3 picture essay:

Outstanding Issues

BoF agenda and discussion

Use this section to take notes during the BoF; if you keep it in the approved spec, use it for summarizing what was discussed and note any options that were rejected.


ConnectingHelpSystems (last edited 2008-08-06 16:35:20 by localhost)