Add docs about Node Types

Trying to answer questions raised in
#470

README.md

@@ -46,16 +46,11 @@ Websites can detect if `window.ipfs` exists and opt-in to use it instead of crea
 It saves system resources and battery (on mobile), avoids the overhead of peer discovery/connection, enables shared repository access and more!
 Make sure to read our [notes on `window.ipfs`](https://github.com/ipfs-shipyard/ipfs-companion/blob/master/docs/window.ipfs.md), where we explain it in-depth and provide examples on how to use it your own dapp.
 
-#### Embedded `js-ipfs` Node
+#### Toggle Between Embedded and External Node
 
 The Browser Action menu provides a toggle for switching  between embedded,
 in-memory `js-ipfs` and external IPFS node accessed over HTTP API.
-The embedded node is great for quickly sharing files with someone, or for
-testing a dapp that uses `window.ipfs` without having to install and start up
-your own IPFS daemon.  
-Power users can provide own config (eg. to enable experimental pubsub) via _Preferences_.
-
-**Note:** The embedded node _does not run_ when external node is selected. Every time you switch back to the embedded node, a new instance is created on-demand. It can take [a few seconds](https://user-images.githubusercontent.com/157609/38493690-4a77bd9e-3bf3-11e8-85da-ba06fd94cdbf.gif) for a brand-new node to find peers.
+Read about differences at [docs/node-types](docs/node-types.md).
 
 #### IPFS Status and Context Actions
 

add-on/_locales/en/messages.json

@@ -177,6 +177,10 @@
     "message": "Failed to stop IPFS node",
     "description": "System notification title displayed when stopping an IPFS node fails (notify_stopIpfsNodeErrorTitle)"
   },
+  "option_legend_readMore" : {
+    "message": "Read more",
+    "description": "A generic link in option description on the Preferences screen (option_legend_readMore)"
+  },
   "option_header_nodeType" : {
     "message": "IPFS Node",
     "description": "A section header on the Preferences screen (option_header_nodeType)"

add-on/src/options/forms/experiments-form.js

@@ -82,6 +82,9 @@ function experimentsForm ({
                       ${browser.i18n.getMessage('option_ipfsProxy_link_manage_permissions')}
                     </a>` : html`<del>${browser.i18n.getMessage('option_ipfsProxy_link_manage_permissions')}</del>`}
                 </p>
+                <p><a href="https://github.com/ipfs-shipyard/ipfs-companion/blob/master/docs/window.ipfs.md" target="_blank">
+                  ${browser.i18n.getMessage('option_legend_readMore')}
+                </a></p>
               </dd>
             </dl>
           </label>

add-on/src/options/forms/ipfs-node-form.js

@@ -16,7 +16,12 @@ function ipfsNodeForm ({ ipfsNodeType, ipfsNodeConfig, onOptionChange }) {
           <label for="ipfsNodeType">
             <dl>
               <dt>${browser.i18n.getMessage('option_ipfsNodeType_title')}</dt>
-              <dd>${browser.i18n.getMessage('option_ipfsNodeType_description')}</dd>
+              <dd>
+                ${browser.i18n.getMessage('option_ipfsNodeType_description')}
+                <p><a href="https://github.com/ipfs-shipyard/ipfs-companion/blob/master/docs/node-types.md" target="_blank">
+                  ${browser.i18n.getMessage('option_legend_readMore')}
+                </a></p>
+              </dd>
             </dl>
           </label>
           <select id="ipfsNodeType" name='ipfsNodeType' onchange=${onIpfsNodeTypeChange}>

docs/node-types.md

@@ -0,0 +1,53 @@
+# Node Types in IPFS Companion
+
+![screenshot of node type toggle](https://user-images.githubusercontent.com/157609/39421672-59010924-4c6a-11e8-9e64-6b5d5f5f2768.png)
+
+> **TL;DR** When in doubt, run go-ipfs as External node
+
+## External
+
+_External_ node can be any instance of IPFS daemon that runs outside of web
+browser process and exposes _Gateway_ and writable _API_ over HTTP at TCP ports.
+
+At this time [go-ipfs](https://github.com/ipfs/go-ipfs) daemon is preferred
+implementation. It is easier on CPU and provides `dhtclient` mode which
+decreases ambient bandwidth use and smaller battery drain (key characteristics
+of something that is expected to run in background all the time).
+
+A good practice is to run it on localhost (`127.0.0.1`) as it provides:
+- Increased security (native IPFS used as end-to-end transport)
+- Better UX in web browser (no mixed-content warnings)
+- Improved performance (local loopback is used, no network overhead)
+
+## Embedded
+
+
+_Embedded_ node is a js-ipfs instance running in browser (in-memory), without need for
+any external software.
+
+It is great for quickly sharing files with someone, or for testing a dapp that
+uses `window.ipfs` without having to install and start up your own IPFS daemon.
+
+Power users can provide [custom config](https://github.com/ipfs/js-ipfs#faq) (eg. to enable experimental pubsub) [via _Preferences_](https://user-images.githubusercontent.com/157609/38084660-0b97c0cc-334e-11e8-9368-823345ced67f.png)
+
+**Note** that Embedded js-ipfs running within webextension (browser context) comes with some limitations:
+
+- Can't act as an HTTP gateway (extension uses public one as a fallback)
+- Known to be CPU-hungry
+  ([#450](https://github.com/ipfs-shipyard/ipfs-companion/issues/450),
+  [ipfs/js-ipfs#1190](https://github.com/ipfs/js-ipfs/issues/1190)) over time,
+- Lack of connection closing
+  ([ipfs/js-ipfs#962](https://github.com/ipfs/js-ipfs/issues/962)
+- The Embedded node _does not run_ when External node is selected.  Every time
+  you switch back to the embedded node, a new instance is created on-demand. It
+  can take [a few
+  seconds](https://user-images.githubusercontent.com/157609/38493690-4a77bd9e-3bf3-11e8-85da-ba06fd94cdbf.gif)
+  for a brand-new node to find peers.
+
+When in doubt, run go-ipfs as External node instead.
+
+## (Public)
+
+Public node is used as an implicit fallback for its Gateway functionality when External node is offline or Embedded node is used.
+It does not expose API port.
+