Improve Help page

Closes #676.

assets/javascripts/templates/pages/help_tmpl.coffee

@@ -1,47 +1,68 @@
-ctrlKey = if $.isMac() then 'cmd' else 'ctrl'
-navKey = if $.isMac() then 'cmd' else 'alt'
+app.templates.helpPage = ->
+  ctrlKey = if $.isMac() then 'cmd' else 'ctrl'
+  navKey = if $.isMac() then 'cmd' else 'alt'
 
-app.templates.helpPage = """
+  aliases_one = {}
+  aliases_two = {}
+  keys = Object.keys(app.models.Entry.ALIASES)
+  middle = Math.ceil(keys.length / 2) - 1
+  for key, i in keys
+    (if i > middle then aliases_two else aliases_one)[key] = app.models.Entry.ALIASES[key]
+
+  """
   <nav class="_toc" role="directory">
     <h3 class="_toc-title">Table of Contents</h3>
     <ul class="_toc-list">
+      <li><a href="#managing-documentations">Managing Documentations</a>
       <li><a href="#search">Search</a>
       <li><a href="#shortcuts">Keyboard Shortcuts</a>
       <li><a href="#aliases">Search Aliases</a>
     </ul>
   </nav>
 
-  <h1 class="_lined-heading">Help</h2>
+  <h1 class="_lined-heading">User Guide</h2>
+
+  <h2 class="_block-heading" id="managing-documentations">Managing Documentations</h2>
+  <p>
+    Documentations can be enabled and disabled in the <a href="/settings">Preferences</a>.
+    Alternatively, you can enable a documentation by searching for it in the main search
+    and clicking the "Enable" link in the results.
+    For faster and better search, only enable the documentations you plan on actively using.
+  <p>
+    Once a documentation is enabled, it becomes part of the search and its content can be downloaded for offline access — and faster page loads when online — in the <a href="/offline">Offline</a> area.
 
   <h2 class="_block-heading" id="search">Search</h2>
   <p>
-    The search is case-insensitive. It supports fuzzy matching
+    The search is case-insensitive and ignores whitespace. It supports fuzzy matching
     (e.g. <code class="_label">bgcp</code> matches <code class="_label">background-clip</code>)
-    and aliases (<a href="#aliases">full list</a> below).
+    as well as aliases (full list <a href="#aliases">below</a>).
   <dl>
     <dt id="doc_search">Searching a single documentation
     <dd>
-      You can scope the search to a single documentation by typing its name (or an abbreviation)
-      and pressing <code class="_label">Tab</code> (<code class="_label">Space</code> on mobile devices).
+      The search can be scoped to a single documentation by typing its name (or an abbreviation)
+      and pressing <code class="_label">tab</code> (<code class="_label">space</code>&nbsp;on mobile).
       For example, to search the JavaScript documentation, enter <code class="_label">javascript</code>
-      or <code class="_label">js</code>, then <code class="_label">Tab</code>.<br>
-      To clear the current scope, empty the search field and hit <code class="_label">Backspace</code>.
+      or <code class="_label">js</code>, then <code class="_label">tab</code>.<br>
+      To clear the current scope, empty the search field and hit <code class="_label">backspace</code> or
+      <code class="_label">esc</code>.
     <dt id="url_search">Prefilling the search field
     <dd>
-      The search field can be prefilled from the URL by visiting <a href="/#q=keyword" target="_top">devdocs.io/#q=keyword</a>.
+      The search can be prefilled from the URL by visiting <a href="/#q=keyword" target="_top">devdocs.io/#q=keyword</a>.
       Characters after <code class="_label">#q=</code> will be used as search query.<br>
-      To search a single documentation, add its name and a space before the keyword:
+      To search a single documentation, add its name (or an abbreviation) and a space before the keyword:
       <a href="/#q=js%20date" target="_top">devdocs.io/#q=js date</a>.
     <dt id="browser_search">Searching using the address bar
     <dd>
       DevDocs supports OpenSearch. It can easily be installed as a search engine on most web browsers:
       <ul>
-        <li>On Chrome, the setup is done automatically. Simply press <code class="_label">Tab</code> when devdocs.io is autocompleted
+        <li>On Chrome, the setup is done automatically. Simply press <code class="_label">tab</code> when devdocs.io is autocompleted
             in the omnibox (to set a custom keyword, click <em>Manage search engines\u2026</em> in Chrome's settings).
         <li>On Firefox, open the search engine list (icon in the search bar) and click <em>Add "DevDocs Search"</em>.
             DevDocs is now available in the search bar. You can also search from the location bar by following
             <a href="https://support.mozilla.org/en-US/kb/how-search-from-address-bar">these instructions</a>.
   </dl>
+  <p>
+    <i>Note: the above search features only work for documentations that are enabled.</i>
 
   <h2 class="_block-heading" id="shortcuts">Keyboard Shortcuts</h2>
   <h3 class="_shortcuts-title">Sidebar</h3>
@@ -95,8 +116,8 @@ app.templates.helpPage = """
       <code class="_shortcut-code">ctrl + ,</code>
     <dd class="_shortcuts-dd">Open preferences
     <dt class="_shortcuts-dt">
-      <code class="_shortcut-code">escape</code>
-    <dd class="_shortcuts-dd">Reset UI
+      <code class="_shortcut-code">esc</code>
+    <dd class="_shortcuts-dd">Clear search field / reset UI
     <dt class="_shortcuts-dt">
       <code class="_shortcut-code">?</code>
     <dd class="_shortcuts-dd">Show this page
@@ -118,11 +139,19 @@ app.templates.helpPage = """
     continue to type and it will refocus the search field and start showing new results.
 
   <h2 class="_block-heading" id="aliases">Search Aliases</h2>
+  <div class="_aliases">
+    <table>
+      <tr>
+        <th>Word
+        <th>Alias
+      #{("<tr><td class=\"_code\">#{key}<td class=\"_code\">#{value}" for key, value of aliases_one).join('')}
+    </table>
     <table>
       <tr>
         <th>Word
         <th>Alias
-    #{("<tr><td class=\"_code\">#{key}<td class=\"_code\">#{value}" for key, value of app.models.Entry.ALIASES).join('')}
+      #{("<tr><td class=\"_code\">#{key}<td class=\"_code\">#{value}" for key, value of aliases_two).join('')}
     </table>
+  </div>
   <p>Feel free to suggest new aliases on <a href="https://github.com/Thibaut/devdocs/issues/new">GitHub</a>.
 """

assets/javascripts/views/content/static_page.coffee

@@ -4,7 +4,7 @@ class app.views.StaticPage extends app.View
   @titles:
     about:    'About'
     news:     'News'
-    help:     'Help'
+    help:     'User Guide'
     notFound: '404'
 
   deactivate: ->

assets/stylesheets/components/_content.scss

@@ -354,6 +354,20 @@
   @extend %label;
 }
 
+//
+// Search aliases
+//
+
+._aliases {
+  display: flex;
+  justify-content: space-between;
+
+  > table {
+    margin-top: 0;
+    width: calc(50% - 0.5rem);
+  }
+}
+
 //
 // Utilities
 //

views/app.erb

@@ -23,7 +23,7 @@
       <a href="/settings" class="_menu-link">Preferences</a>
       <a href="/offline" class="_menu-link">Offline Data</a>
       <a href="/news" class="_menu-link">Changelog</a>
-      <a href="/help" class="_menu-link">Help</a>
+      <a href="/help" class="_menu-link">Guide</a>
       <a href="/about" class="_menu-link">About</a>
     </nav>
   </header>