Labs/Ubiquity/Documentation/Documentation Style Guidelines: Difference between revisions
Indolering (talk | contribs) m (Created page with '= Minimalist Documentation = Minimalist documentation is a modality of documentation emphasizes three principals: == Procedural Instruction == Trade conceptual overviews with ex...') |
m (Minor fixes and added a wikipedia link) |
||
| Line 6: | Line 6: | ||
== Minimal Wording == | == Minimal Wording == | ||
Get a copy of Strunk and White's The Elements of Style. Facilitate a users search for information by removing obstacles blocking their path- excess verbiage. Be ruthless. | Get a copy of Strunk and White's [http://en.wikipedia.org/wiki/The_Elements_of_Style The Elements of Style]. Facilitate a users search for information by removing obstacles blocking their path- excess verbiage. Be ruthless. | ||
== Error Recovery == | == Error Recovery == | ||
Find out what the most common errors are for users and either fix the interface or make the mistake obvious. This should happen in the interface, of course, but changing a wiki-page is much faster. One option is to include screenshots, tightly focused on only relevant information or using a spotlight, with prompts such as, | Find out what the most common errors are for users and either fix the interface or make the mistake obvious. This should happen in the interface, of course, but changing a wiki-page is much faster. One option is to include screenshots, tightly focused on only relevant information or using a spotlight, with prompts such as, "Can you find this on your screen?" | ||
== Guided Discovery == | == Guided Discovery == | ||
| Line 16: | Line 16: | ||
= Ideas for implementation in Ubiquity. = | = Ideas for implementation in Ubiquity. = | ||
Minimalist documentation facilitates casual learning and focus on immediate progress instead of true understanding. People learn and retain better if they process information deeply. The tutorial has served Ubiquity well in that it weeds out users whom would be unable to handle the difficulty of such a situation and only people who know how to work Ubiquity wander into the IRC channel and mailing list. Much as Wikipedia's poor interface prevents many lower-level users from contributing faulty information. | Minimalist documentation facilitates casual learning and focus on immediate progress instead of true understanding. People learn and retain better if they process information deeply. The tutorial has served Ubiquity well in that it weeds out users whom would be unable to handle the difficulty of such a situation and only people who know how to work Ubiquity wander into the IRC channel and mailing list. Much as Wikipedia's poor interface prevents many lower-level users from contributing faulty information. | ||
However, Ubiquity is beyond that era. New users are needed- developers cannot be bogged down in support situations, documentation, etc. | However, Ubiquity is beyond that era. New users are needed- developers cannot be bogged down in support situations, documentation, etc. | ||
== Procedural Instruction == | == Procedural Instruction == | ||
Slash the tutorial, get rid of video overviews, etc, and move straight to the real activities. | Slash the tutorial, get rid of video overviews, etc, and move straight to the real activities. | ||
Documentation should be broken down into the command level with stand-alone examples of each command. | Documentation should be broken down into the command level with stand-alone examples of each command. | ||
# Tap option + space bar | # Tap option + space bar | ||
# Type: wikipedia firefox | # Type: wikipedia firefox | ||
# You should see this exact screen: | # You should see this exact screen: [[Image:]] | ||
# Tap the Enter key to open the Wikipedia article in a new tab | |||
== Minimal Wording == | == Minimal Wording == | ||
Minimal wording extends beyond short sentences, intros, exits, and philosophical reasonings are for blog-posts, not for intros. Users just do not read them, | Minimal wording extends beyond short sentences, intros, exits, and philosophical reasonings are for blog-posts, not for intros. Users just do not read them, | ||
<nowiki> | "<nowiki>[Users]</nowiki> encounter a usability problem on average about '''once every 75 minutes''' and typically spend about '''a minute''' looking for a solution" | ||
In a larger perspective simplifying the help Wiki (users were confused by the Wiki additions) and dumping users directly to help oriented Q/A systems such as Get Satisfaction and Chat rooms. | In a larger perspective simplifying the help Wiki (users were confused by the Wiki additions) and dumping users directly to help oriented Q/A systems such as Get Satisfaction and Chat rooms. | ||
| Line 43: | Line 39: | ||
Even screenshots seem to be unable to cue users that something is wrong. Video and animations may help this. | Even screenshots seem to be unable to cue users that something is wrong. Video and animations may help this. | ||
However, error recovery should be implemented in Ubiquity proper. One avenue is highly optimized error pages. When the parser reaches a level of uncertainty it could dump users to a google search, or another | However, error recovery should be implemented in Ubiquity proper. One avenue is highly optimized error pages. When the parser reaches a level of uncertainty it could dump users to a google search, or another "best effort" end-point, with command documentation embedded in the page- something akin to Google's varied spelling corrections. | ||
Eventually, a continual improvement loop could feed metrics such actions taken after the error page, what input produces error pages, click through of command results, manual selection of auto-suggestions, etc. | Eventually, a continual improvement loop could feed metrics such actions taken after the error page, what input produces error pages, click through of command results, manual selection of auto-suggestions, etc. | ||
Revision as of 15:18, 14 July 2009
Minimalist Documentation
Minimalist documentation is a modality of documentation emphasizes three principals:
Procedural Instruction
Trade conceptual overviews with examples of real tasks and activities. Make each example a self contained unit independent of any other example.
Minimal Wording
Get a copy of Strunk and White's The Elements of Style. Facilitate a users search for information by removing obstacles blocking their path- excess verbiage. Be ruthless.
Error Recovery
Find out what the most common errors are for users and either fix the interface or make the mistake obvious. This should happen in the interface, of course, but changing a wiki-page is much faster. One option is to include screenshots, tightly focused on only relevant information or using a spotlight, with prompts such as, "Can you find this on your screen?"
Guided Discovery
Auto suggest, commercials.
Ideas for implementation in Ubiquity.
Minimalist documentation facilitates casual learning and focus on immediate progress instead of true understanding. People learn and retain better if they process information deeply. The tutorial has served Ubiquity well in that it weeds out users whom would be unable to handle the difficulty of such a situation and only people who know how to work Ubiquity wander into the IRC channel and mailing list. Much as Wikipedia's poor interface prevents many lower-level users from contributing faulty information.
However, Ubiquity is beyond that era. New users are needed- developers cannot be bogged down in support situations, documentation, etc.
Procedural Instruction
Slash the tutorial, get rid of video overviews, etc, and move straight to the real activities.
Documentation should be broken down into the command level with stand-alone examples of each command.
- Tap option + space bar
- Type: wikipedia firefox
- You should see this exact screen: [[Image:]]
- Tap the Enter key to open the Wikipedia article in a new tab
Minimal Wording
Minimal wording extends beyond short sentences, intros, exits, and philosophical reasonings are for blog-posts, not for intros. Users just do not read them,
"[Users] encounter a usability problem on average about once every 75 minutes and typically spend about a minute looking for a solution"
In a larger perspective simplifying the help Wiki (users were confused by the Wiki additions) and dumping users directly to help oriented Q/A systems such as Get Satisfaction and Chat rooms.
Error Recovery
Even screenshots seem to be unable to cue users that something is wrong. Video and animations may help this.
However, error recovery should be implemented in Ubiquity proper. One avenue is highly optimized error pages. When the parser reaches a level of uncertainty it could dump users to a google search, or another "best effort" end-point, with command documentation embedded in the page- something akin to Google's varied spelling corrections.
Eventually, a continual improvement loop could feed metrics such actions taken after the error page, what input produces error pages, click through of command results, manual selection of auto-suggestions, etc.
Guided Instruction
Ubiquity is heavily dependent on it's auto-suggest function. Optimizations are difficult due to the high cost of eye tracking equipment. In the future, a streamed interface could seed different variations.