Ubuntu Wiki

• Launchpad Entry: noneyet

• Packages affected:

STATUS: Early brainstorming

Please feel free to contribute anything that comes to mind.

Summary

User experience with the help system as a whole can be dramatically improved by strengthening the ties between various types of help available. By pushing them into nearly indecent proximity, we can cross breed their respective strengths in reliability and responsiveness.

• the installed documentation's high polish and organization can provide structure for:
• the wiki system, which preserves and consolidates the fresh, ephemeral information from:
• the forum, chat, and question system, whose ease of use the others try to match.

The goal of this spec is to find ways to merge the above components into a fluid system, encouraging acivity and lowering barriers.

Release Note

(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 incorporate chat, suggestion, and request functionality directly on their pages, for streamlined use.

Rationale

When someone needs help with a program, having all the information in one clear and up to date 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 incorporate as many of our support types as possible, you drive most activity to the same point, thus finding and solving issues fastest.

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 an sturdy skeleton on which to grow more user-tended content.

Use Cases

Bob is having trouble with a program. He checks the installed help tool and follows the trail from that package's usage and howto page to the user reported problems section. He does not find his problem in the common problems list, but finds his error message reported recently by another user. There are no suggested solutions yet, so he clicks the "me too" button on that error and goes to check other resources.

Suzy and Jim are experienced users of that package, and they are both there to submit short howto suggestions for that page. They see the increasingly popular error and immediately recognize it as a misconfiguration of a system file about which this program is picky. Their responses to the problem suggesting a fix causes all the people who clicked "me too" on that problem to be notified of feedback/activity on an open issue of theirs when they next check the site.

Joe had reported the issue and got the notification. When he tried their fix it worked, and he closed his issue with "fixed" pointing to their comments. He is one of several who do this, increasing the visibility of their solutions. Someone else soon writes up a nice suggestion explaining this as a common problem with a conflicting package, and how to resolve it.

Sadly, however, there is a gap and no editors are watching that page at this time. In a short while, the open suggestions and issues on this page begin to age without activity either accommodating, incorporating, or rejecting them. Soon the page shows up at the top of the docteam's monitor, letting all members see that part of the wiki is falling unmanaged. Hopefully someone will quickly be free to visit the page, promote the suggestion to a common problem, and tie all the issues to that for resolution, but in the meantime, visitors to that page can still get all the info they need just one layer into user submitted content.

Assumptions

Design

The wiki would become one cohesive entity, the core structure and essential pages of which are closed to editing only by the docteam, which will comprise the solid trunk of the offline documentation. Connected to this core structure are branching collections of pages for various topics and software packages, managed by many individual groups of proven responsible editors. These pages would also be considered official documentation and should only need cursory approval of updates for incorporation into the offline documentation. However, all online pages allow users to optionally view user submitted suggestions, add suggestions of their own, or critique existing suggestions. This allows editors to incorporate popular submitted content quickly and easily.

Furthermore, all users can create and control their own personal sections of the wiki, creating subpages that they can link to official documentation (and submit as howtos or resources for official adoption). This allows them to practice not only content editing, but also approving and incorporating the feedback of others.

Create a blueprint for the hierarchal structure, and implementation in moinmoin ACLs

Create a blueprint for easily incorporating various types of user submitted content

Create a blueprint for managing the obtrusiveness of user content

Create a blueprint for user managed popularity and quality control

Create a blueprint for overview, karma distribution, and abuse prevention

Create a blueprint for conflict/duplication avoidance in user suggestions

Connect and update blueprint for managing offline caching of help docs LinkingDesktopToOnlineHelp

Connect to blueprint for linking to external resources ExternalLinksRedirects

Implementation

This section should describe a plan of action (the "how") to implement the changes discussed. Could include subsections like:

• installed help system stays up to date with installed software
• installed help system smoothly transitions to more information online
• online help system already knows users of related systems (launchpad, forums)
• allow suggestions or questions in just a couple clicks
• smartly encourage user moderation and user support
• homogenize the interface of all systems, adding only minimum changes as you transition
• incorporate karma across the systems
• tag all package feedback pages with how closely dev/maintainers/packager watch it, and refer to their pages

UI Changes

Issues, responses

• one plain text content box, no markup
• one image per post, local use only
• short title for first post
• responses have choice of "I also want to know", or "Suggest a solution"
• content optional for dittos
• threads you have been active in for last X days show.

Suggestions:

• Choose a target section/issue to comment on
• Choose to modify the target section, and recieve a copy of current content
• only allow targeting of up to one paragraph

Should cover changes required to the UI, or specific UI that is required to implement this

Code Changes

Code changes should include an overview of what needs to change, and in some cases even the specific details.

Migration

Include:

• data migration, if any
• redirects from old URLs to new ones, if any
• how users will be pointed to the new way of doing things, if necessary.

Test/Demo Plan

It's important that we are able to test new features, and demonstrate them to users. Use this section to describe a short plan that anybody can follow that demonstrates the feature is working. This can then be used during CD testing, and to show off after release.

This need not be added or completed until the specification is nearing beta.

Outstanding Issues

• The only person pushing for this idea at this time is WAY over his head
• While it all seems possible, the features would probably take time to develop
• By its nature, this spec shoots for massive changes in the way the system works

BoF agenda and discussion

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

CategorySpec