ConnectingHelpSystems
2605
Comment:
|
10474
|
Deletions are marked like this. | Additions are marked like this. |
Line 1: | Line 1: |
## page was renamed from MergeHelpDocsWikiForum ## page was renamed from MergeDocsWikiHelp ## page was renamed from BrainstormingWebsiteSpec |
|
Line 3: | Line 6: |
''Please check the status of this specification in Launchpad before editing it. If it is Approved, contact the Assignee or another knowledgeable person before making changes.'' * '''Launchpad Entry''': UbuntuSpec:foo |
* '''Launchpad Entry''': UbuntuSpec:noneyet |
Line 8: | Line 9: |
Work in progress, early drafting. | STATUS: Firming up planning, accumulating designs and mockup images ''This is a master spec for several related topics, and is currently in an early state of development by one person. Please feel free to contribute anything that comes to mind.'' |
Line 11: | Line 15: |
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 12: | Line 17: |
This should provide an overview of the issue/functionality/change proposed here. Focus here on what will actually be DONE, summarising that so that other people don't have to read the whole spec. | 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, and question systems, whose simplicity kick-starts involvement from: * the users, who keep coming back because they find all the best resources connecting here |
Line 14: | Line 23: |
== Release Note == | I selected the wiki system as the central point because of it's flexible and visible nature. |
Line 16: | Line 25: |
This section should include a paragraph describing the end-user impact of this change. It is meant to be included in the release notes of the first release in which it is implemented. (Not all of these will actually be included in the release notes, at the release manager's discretion; but writing them is a useful exercise.) | == 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. |
Line 18: | Line 28: |
It is mandatory. | The online help pages now link directly to appropriate chat, forums, and external information. |
Line 22: | Line 32: |
This should cover the _why_: why is this change being proposed, what justifies it, where we see this justified. | 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 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, or by example). |
Line 25: | Line 39: |
(Update this to match the more recent, more streamlined ideas) 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. |
|
Line 27: | Line 50: |
* 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 |
|
Line 28: | Line 54: |
== Design == | == Design Images + Implementation Sub-Specs == |
Line 30: | Line 56: |
You can have subsections that better describe specific parts of the issue. | === Wiki + IRC === Spec: TBA |
Line 32: | Line 59: |
== Implementation == | Status: Design and Brainstorming |
Line 34: | Line 61: |
This section should describe a plan of action (the "how") to implement the changes discussed. Could include subsections like: | 3 picture essay: * show a teaser at the top of the page suggesting chatting about this topic * show the expanded chat info section with channel and irc options * show the simple web chat interface |
Line 36: | Line 66: |
=== UI Changes === | Notes to push to spec: * once activated, the teaser expands to offer links, explanation, and mini-chat * a flash or java chat client would have a simple interface, as most options are hard-coded * suggest appropriate channel at the top of each page * allow users to open a tiny, basic in frame java/flash irc client * hardcode the appropriate server and channel for the page's content * mimic the ubuntu help ui as closely as possible to help the learning curve * look for a good way to manage channel selection/inheritance for pages |
Line 38: | Line 75: |
Should cover changes required to the UI, or specific UI that is required to implement this | === Wiki + Forums === Spec: TBA |
Line 40: | Line 78: |
=== Code Changes === | Status: Design and Brainstorming |
Line 42: | Line 80: |
Code changes should include an overview of what needs to change, and in some cases even the specific details. | 3 picture essay: * [http://nmonk.org/livetree/Comments.jpg user comments are obvious but not intrusive] * show simple new comment screen - taking the step to activity is simple * show response and rating screen - and the community is self-reinforcing |
Line 44: | Line 85: |
=== Migration === | Notes to push to spec: * [http://nmonk.org/livetree/Comment.jpg what the comment option could look like with no comments (This could be made transparent unless the mouse is over that section.)] * [http://nmonk.org/livetree/OpenComments.jpg when browsing comments, the line becomes a box, showing the section to which the comments apply] * adding a comment should be barely more complicated than chat * replying to a comment gives a chance to agree or disagree (or report for content) * highly rated comments become more visible, pop out to all? * rated down comments become less visible - show to only 1/X viewers * allow users to request help/more information * keep track of the age of requests, and list them for the user * make clear notification when there has been feedback on their request * track questions from accounts with designated support personnel, for their support teams to respond? (Son, Helpdesk, Paid Support Companies) |
Line 46: | Line 97: |
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. |
=== Fresh + Managed === Spec: TBA |
Line 51: | Line 100: |
== Test/Demo Plan == | Status: Design and Brainstorming |
Line 53: | Line 102: |
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. | 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 55: | Line 107: |
This need not be added or completed until the specification is nearing beta. | Notes to push to spec: * you also have a choice of suggesting an edit, which is just slightly more complicated * others can approve or dissaprove of your edit easily * editors can incorporate your suggested edit just as easily * on managed pages, allow users to suggest changes with the same interface * allow other users to see and rate those suggestions * provide fast notification and review of suggestions in control panel * implement karma for useful suggestions and reviews * make the interface for suggesting and making changes nearly identical * use === 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: 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 Notes to push to spec: * standardize on a section near the top of the page * make ui match changing other page content, managed or not * integrate with the control panel for centralization * show all pages that use the link |
Line 59: | Line 153: |
This should highlight any issues that should be addressed in further specifications, and not problems with the specification itself; since any specification with problems cannot be approved. | * 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 63: | Line 162: |
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
This is a master spec for several related topics, and is currently in an early state of development by one person. 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, and question 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 because of it's flexible and visible nature.
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 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 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, or by example).
Use Cases
(Update this to match the more recent, more streamlined ideas)
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
- 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
Wiki + IRC
Spec: TBA
Status: Design and Brainstorming
3 picture essay:
- show a teaser at the top of the page suggesting chatting about this topic
- show the expanded chat info section with channel and irc options
- show the simple web chat interface
Notes to push to spec:
- once activated, the teaser expands to offer links, explanation, and mini-chat
- a flash or java chat client would have a simple interface, as most options are hard-coded
- suggest appropriate channel at the top of each page
- allow users to open a tiny, basic in frame java/flash irc client
- hardcode the appropriate server and channel for the page's content
- mimic the ubuntu help ui as closely as possible to help the learning curve
- look for a good way to manage channel selection/inheritance for pages
Wiki + Forums
Spec: TBA
Status: Design and Brainstorming
3 picture essay:
[http://nmonk.org/livetree/Comments.jpg user comments are obvious but not intrusive]
- show simple new comment screen - taking the step to activity is simple
- show response and rating screen - and the community is self-reinforcing
Notes to push to spec:
[http://nmonk.org/livetree/Comment.jpg what the comment option could look like with no comments (This could be made transparent unless the mouse is over that section.)]
[http://nmonk.org/livetree/OpenComments.jpg when browsing comments, the line becomes a box, showing the section to which the comments apply]
- adding a comment should be barely more complicated than chat
- replying to a comment gives a chance to agree or disagree (or report for content)
- highly rated comments become more visible, pop out to all?
- rated down comments become less visible - show to only 1/X viewers
- allow users to request help/more information
- keep track of the age of requests, and list them for the user
- make clear notification when there has been feedback on their request
- track questions from accounts with designated support personnel, for their support teams to respond? (Son, Helpdesk, Paid Support Companies)
Fresh + Managed
Spec: TBA
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
Notes to push to spec:
- you also have a choice of suggesting an edit, which is just slightly more complicated
- others can approve or dissaprove of your edit easily
- editors can incorporate your suggested edit just as easily
- on managed pages, allow users to suggest changes with the same interface
- allow other users to see and rate those suggestions
- provide fast notification and review of suggestions in control panel
- implement karma for useful suggestions and reviews
- make the interface for suggesting and making changes nearly identical
- use
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: 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
Notes to push to spec:
- standardize on a section near the top of the page
- make ui match changing other page content, managed or not
- integrate with the control panel for centralization
- show all pages that use the link
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)