ConnectingHelpSystems
|
Size: 8547
Comment:
|
← Revision 25 as of 2008-08-06 16:35:20 ⇥
Size: 8299
Comment: converted to 1.6 markup
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| ## page was renamed from MergeHelpDocsWikiForum | |
| Line 8: | Line 9: |
| STATUS: Early brainstorming | STATUS: Firming up planning, accumulating designs and mockup images |
| Line 10: | Line 11: |
| ''Please feel free to contribute anything that comes to mind.'' | Contributors: Nmonk, DuncanLithgow |
| Line 12: | Line 13: |
| ''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.'' | |
| Line 14: | Line 16: |
| 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 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. |
| Line 16: | Line 18: |
| * the installed documentation's high polish and organization can provide structure for: | Ideally: * the installed documentation's high polish and organization provides structure for: * the [[https://help.ubuntu.com/|wiki system]], which preserves and consolidates the fresh, ephemeral information from: * the [[http://ubuntuforums.org/|forum]], chat (irc.freenode.net #ubuntu), and [[https://answers.edge.launchpad.net/ubuntu/|Answers]] systems, whose simplicity kick-starts involvement from: * the users, who keep coming back because they find all the best resources connecting here |
| Line 18: | Line 24: |
| * the wiki system, which preserves and consolidates the fresh, ephemeral information from: | 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. |
| Line 20: | Line 26: |
| * 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) |
== Hypothetical Release Notes == |
| Line 29: | Line 29: |
| The online help pages now incorporate chat, suggestion, and request functionality directly on their pages, for streamlined use. | The online help pages now link directly to appropriate chat, forums, and external information. |
| Line 33: | Line 33: |
| 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. | 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. |
| Line 35: | Line 35: |
| 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. | 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). |
| Line 39: | Line 41: |
| 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. | 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... |
| Line 41: | Line 43: |
| 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. | (Installed to Online) |
| Line 43: | Line 45: |
| 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. | ... 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... |
| Line 45: | Line 47: |
| 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. | (Internal to External) ... 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 ... (Wiki to Forums) ... 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... (Wiki to Chat) ... 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 ... (Suggestions to Managed) ... 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. |
| Line 48: | Line 64: |
| * the installed docs and the online help aren't separated by insurmountable legal barriers * the administrative teams of the parts of the support system are willing to cooperate * massive changes like this are decomposable into achievable sub-projects == Design Images + Implementation Sub-Specs == |
|
| Line 50: | Line 71: |
| === Installed + Online === Spec: LinkingDesktopToOnlineHelp |
|
| Line 51: | Line 74: |
| == Design == | Status: Design and Brainstorming to update existing spec |
| Line 53: | Line 76: |
| 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. | 3 picture essay: * show help screen directing to online : installed help points you towards more information * show control panel : the installed help is the solid core of online help * show update window : installed help can sync with your system updates |
| Line 55: | Line 81: |
| 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 |
Notes to push to spec: * consider basing installed help on a web caching tool, thus direct transition * add updating and syncing with installed versions to installed help * separate navigation structure management from page content management * get a good control panel for managing overall structure, status, and permissions * figure out how to safely tie in unmanaged wiki pages |
| Line 96: | Line 89: |
| === UI Changes === | === Internal + External === Spec: ExternalLinksRedirects |
| Line 98: | Line 92: |
| Issues, responses | Status: Add to existing draft |
| Line 100: | Line 94: |
| * 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 |
3 picture essay: * show section at the top of the page : collect useful external resources * show link updater interface : update them all at once if the situation changes * show link approval interface : catch and correct mistakes |
| Line 121: | Line 100: |
| === Wiki + IRC === Spec: ConnectingWikiToChat |
|
| Line 122: | Line 103: |
| Should cover changes required to the UI, or specific UI that is required to implement this | Status: Design and Brainstorming |
| Line 124: | Line 105: |
| === Code Changes === | 3 picture essay: * [[http://nmonk.org/livetree/ChatLink.jpg|suggest appropriate channels for chat on each page]] * [[http://nmonk.org/livetree/ChatInfo.jpg|give info and links about IRC and offer web chat]] * show a simple web chat interface (if logged in) |
| Line 126: | Line 110: |
| Code changes should include an overview of what needs to change, and in some cases even the specific details. | |
| Line 128: | Line 111: |
| === Migration === | === Wiki + Forums === Spec: ConnectingWikiToForums |
| Line 130: | Line 114: |
| 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. |
Status: Design and Brainstorming |
| Line 135: | Line 116: |
| == Test/Demo Plan == | 3 picture essay: * [[http://nmonk.org/livetree/Comments.jpg|user comments can be obvious without being distracting]] * show simple new comment screen - taking the step to activity can be simple * show response and rating screen - and the community is self-reinforcing |
| Line 137: | Line 121: |
| 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. | |
| Line 139: | Line 122: |
| This need not be added or completed until the specification is nearing beta. | === Fresh + Managed === Spec: ConnectingSuggestionsToManagedPages Status: Design and Brainstorming 3 picture essay: * show suggestion start : managed pages are still open for feedback * show suggestion finish : it's easy to avoid duplicating work * show editor apply screen : and the editors can apply your changes quickly |
| Line 143: | Line 135: |
| * 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 |
* the only person pushing for these ideas at this time is WAY over his head * said person lacks clear understanding of all parts of the current system * 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 * the fresh + managed sub-spec is based on the idea of much finer grained, paragraph based wiki updates, not quite moin's page at a time system, which makes implementing that spec a bit problematic * the author of this spec is quite optimistically paranoid, and probably envisions much more managed pages than the current system (where all new users can modify almost all wiki pages on the wiki.ubuntu side) |
| Line 149: | Line 144: |
| 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. | 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. - What the heck is BoF? |
Launchpad Entry: noneyet
Packages affected:
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.
Summary
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.
Ideally:
- the installed documentation's high polish and organization provides structure for:
the wiki system, which preserves and consolidates the fresh, ephemeral information from:
the forum, chat (irc.freenode.net #ubuntu), and Answers systems, whose simplicity kick-starts involvement from:
- the users, who keep coming back because they find all the best resources connecting here
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.
Rationale
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...
- (Installed to Online)
... 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...
- (Internal to External)
... 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 ...
- (Wiki to Forums)
... 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...
- (Wiki to Chat)
... 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 ...
- (Suggestions to Managed)
... 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.
Assumptions
- the installed docs and the online help aren't separated by insurmountable legal barriers
- the administrative teams of the parts of the support system are willing to cooperate
- massive changes like this are decomposable into achievable sub-projects
Design Images + Implementation Sub-Specs
Installed + Online
Spec: LinkingDesktopToOnlineHelp
Status: Design and Brainstorming to update existing spec
3 picture essay:
- show help screen directing to online : installed help points you towards more information
- show control panel : the installed help is the solid core of online help
- show update window : installed help can sync with your system updates
Notes to push to spec:
- consider basing installed help on a web caching tool, thus direct transition
- add updating and syncing with installed versions to installed help
- separate navigation structure management from page content management
- get a good control panel for managing overall structure, status, and permissions
- figure out how to safely tie in unmanaged wiki pages
Internal + External
Spec: ExternalLinksRedirects
Status: Add to existing draft
3 picture essay:
- show section at the top of the page : collect useful external resources
- show link updater interface : update them all at once if the situation changes
- show link approval interface : catch and correct mistakes
Wiki + IRC
Spec: ConnectingWikiToChat
Status: Design and Brainstorming
3 picture essay:
- show a simple web chat interface (if logged in)
Wiki + Forums
Spec: ConnectingWikiToForums
Status: Design and Brainstorming
3 picture essay:
- show simple new comment screen - taking the step to activity can be simple
- show response and rating screen - and the community is self-reinforcing
Fresh + Managed
Spec: ConnectingSuggestionsToManagedPages
Status: Design and Brainstorming
3 picture essay:
- show suggestion start : managed pages are still open for feedback
- show suggestion finish : it's easy to avoid duplicating work
- show editor apply screen : and the editors can apply your changes quickly
Outstanding Issues
- the only person pushing for these ideas at this time is WAY over his head
- said person lacks clear understanding of all parts of the current system
- 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
- the fresh + managed sub-spec is based on the idea of much finer grained, paragraph based wiki updates, not quite moin's page at a time system, which makes implementing that spec a bit problematic
- the author of this spec is quite optimistically paranoid, and probably envisions much more managed pages than the current system (where all new users can modify almost all wiki pages on the wiki.ubuntu side)
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.
- - What the heck is BoF?
ConnectingHelpSystems (last edited 2008-08-06 16:35:20 by localhost)