Revert "Group revert of the following commits for design docs:"
This reverts commit c9506415d533c61a9607c5b61a1993747bafb406.
diff --git a/docs/html/design/patterns/help.jd b/docs/html/design/patterns/help.jd
new file mode 100644
index 0000000..e42ea26
--- /dev/null
+++ b/docs/html/design/patterns/help.jd
@@ -0,0 +1,114 @@
+page.title=Help
+@jd:body
+
+<p>We wish we could guarantee that if you follow every piece of advice on this website, everyone will be able to learn and use your app without a hitch. Sadly, that's not the case.</p>
+
+<p>Some of your users will run into questions or problems along the way. They'll be looking for answers <strong>within your app</strong>, and if they don't find them quickly, they may leave and never come back.</p>
+
+<p>This page covers design patterns for making help accessible in your app and tips for creating help content for users who are eager for assistance.</p>
+
+<h2 id="your-app">Designing Help into Your App</h2>
+
+<h3>Don't show unsolicited help, except in very limited cases</h3>
+<p>Naturally, you want everyone to quickly learn the ropes, discover the cool features, and get the most out of your app. So you might be tempted to present a one-time introductory slideshow, video, or splash screen to all new users when they first open the app. Or you might be drawn to the idea of displaying helpful text bubbles or dialogs when users interact with certain features for the first time.</p>
+<p>In almost all cases, we advise <strong>against</strong> approaches like these because:</p>
+<ul>
+ <li><strong>They're interruptions.</strong> People will be eager to start using your app, and anything you put in front of them will feel like an obstacle or possibly an annoyance, despite your good intentions. And because they didn't ask for it, they probably won't pay close attention to it.</li>
+ <li><strong>They're usually not necessary.</strong> If you have usability concerns about an aspect of your app, don't just throw help at the problem. Try to solve it in the UI. Apply Android design patterns, styles, and building blocks, and you'll go a long way in reducing the need to educate your users.</li>
+</ul>
+<p>The only reason for showing pure help content to new users unsolicited is:<br>
+<em>To teach high value functionality that's only available through an atypical use of a gesture.</em></p>
+
+<p>For example, we use help content to teach users how to place apps on their Home Screen. This functionality is:</p>
+<div class="layout-content-row">
+ <div class="layout-content-col span-8">
+ <ol>
+ <li><strong>High value</strong>
+ <p style="margin-top="0">Without it, users wouldn't be able to customize the most frequently-visited Android screen to meet their needs.</p></li>
+ <li><strong>Available only through a gesture</strong>
+ <p style="margin-top="0">Users can't do this through a button or a menu.</p></li>
+ <li><strong>Atypical for the gesture</strong>
+ <p style="margin-top="0">Many high value functions invoked through a gesture - like scrolling, swiping tabs, and turning pages - are common and yield expected results. Users will be able to discover them in your app, and unsolicited help is unnecessary. But here, the gesture does something unexpected: press and hold doesn't just select an app, it also immediately navigates to the Home Screen and creates a shortcut to the app that can then be dragged around.</p></li>
+ </ol>
+ <p>However, this is an exceptional case. Most functionality doesn't meet all three of these criteria.</p>
+ </div>
+ <div class="layout-content-col span-5">
+ <img src="{@docRoot}design/media/help_cling.png">
+ <div class="figure-caption">
+ The first time each user visits the All Apps screen, a semi-transparent overlay appears to teach an important gesture.
+ </div>
+ </div>
+ <p class="clearfix">Bottom line: when it comes to offering help in your app, it's much better to <strong>let users come to you</strong> when they need it.</p>
+</div>
+
+<h3 id="standard-design">Follow the standard design for navigating to help</h3>
+
+<p>On every screen in your app, offer help in the <a href="{@docRoot}design/patterns/actionbar.html">action overflow</a>. Always make it the very last item in the menu and label it "Help".</p>
+
+<div class="layout-content-row">
+ <div class="layout-content-col span-7">
+ <img src="{@docRoot}design/media/help_overflow.png">
+ </div>
+ <div class="layout-content-col span-6">
+ <img src="{@docRoot}design/media/help_solo_overflow.png">
+ <div class="figure-caption">
+ Even if your screen has no other action overflow items, "Help" should appear there and not be promoted to the action bar.
+ </div>
+ </div>
+ <p>We've established this standard design so that when users are desperate for help, they won't have to hunt to find it (see design principle: <a href="{@docRoot}design/get-started/principles.html#give-me-tricks">Give me tricks that work everywhere</a>).</p>
+</div>
+
+<h3 id="help-urgent">Assume that every call for help is urgent</h3>
+
+<p>In addition to help, you might want to expose miscellaneous other information, such as copyright info, credits, terms of service, and privacy policy.</p>
+
+<p>Let users access this information through your Help menu item, but don't give it prominence equal to the core help content. Optimize the flow for people who have urgent questions about how to do something or why something is happening in your app. The smaller subset of users who are looking for legal fine print or the names of the people who created the app won't be as burdened by taking a few extra steps.</p>
+
+<p>The same is true for any communication options you might want to provide, such as contacting customer support or submitting feedback. Offer these options in a way that doesn't add an extra step before users see help. When you put the help content forward, you increase the likelihood that users will find the answers on their own, which in turn reduces your support costs.</p>
+
+<p>When someone chooses "Help":</p>
+
+<div class="layout-content-row">
+ <div class="layout-content-col span-4">
+ <img src="{@docRoot}design/media/help_dont.png">
+ </div>
+ <div class="layout-content-col span-4">
+ <img src="{@docRoot}design/media/help_better.png">
+ </div>
+ <div class="layout-content-col span-5">
+ <img src="{@docRoot}design/media/help_evenbetter.png">
+ </div>
+</div>
+
+<div class="layout-content-row">
+ <div class="layout-content-col span-4">
+ <h4 class="do-dont-label bad">Don't</h4>
+ <p>Present a dialog asking them to choose between help and other options.</p>
+ </div>
+ <div class="layout-content-col span-4">
+ <h4 class="do-dont-label good">Better</h4>
+ <p>Immediately launch a web browser with help content. Place other options in a footer.</p>
+ </div>
+ <div class="layout-content-col span-5">
+ <h4 class="do-dont-label good">Even Better</h4>
+ <p>Build a help screen in your app and offer other options in the action bar.</p>
+ <p>This requires more development work than launching a web browser, but it's a nicer experience for users because they don't leave your app to get the help they need and doesn't require a network connection.</p>
+ </div>
+</div>
+
+<h2>Principles for Writing On-Screen Help Content</h2>
+
+<h4>Help is part of the UI</h4>
+<p>On-screen help is an extension of your app's UI, not a description of it. All words on the screen from the core app to the help should follow our <a href="{@docRoot}design/style/writing.html">Writing Style</a> principles so that the end-to-end experience feels seamless and cohesive.</p>
+
+<h4>Make every pixel count</h4>
+<p>It's not necessary to document every single detail about your app, especially things that are extremely apparent just by looking at the UI, or behaviors that are standard for the platform. Surface just the key additional information that the on-screen text doesn't have room to describe, in a way that makes it easy to map to the screen.</p>
+
+<h4>Pictures are faster than words</h4>
+<p>In describing key UI elements and providing step-by-step instructions, consider combining text with icons, partial screenshots with callouts, and other imagery. You'll need fewer words to explain things, and users will absorb the information more quickly.</p>
+
+<h4>Help me scan, not read</h4>
+<p>People don't read help from start to finish. They scan around, looking for a piece of information containing the answer they need. Make it less burdensome with friendly formatting and layout choices like bold headings, bulleted and numbered lists, tables, and white space between paragraphs. And if you have a large amount of content, divide it into multiple screens to cut down on scrolling.</p>
+
+<h4>Take me straight to the answer</h4>
+<p>What's better than a screen that's easy to scan? A screen that requires no scanning at all because the answer's right there. Consider having each screen in your app navigate to help that's relevant just to that screen. We call this <em>contextual help</em>, and it's the holy grail of user assistance. If you take this approach, be sure to also provide a way to get to the rest of the help content.</p>
\ No newline at end of file