📝 Update readme and docs

Author: viddo

README.md

@@ -1,29 +1,26 @@
-# Textual Velocity for Atom [![Travis Build Status](http://travis-ci.org/viddo/atom-textual-velocity.png?branch=master)](http://travis-ci.org/viddo/atom-textual-velocity) [![CircleCI Build status](https://circleci.com/gh/viddo/atom-textual-velocity/tree/clean.png?style=shield&circle-token=:circle-token)](https://circleci.com/gh/viddo/atom-textual-velocity)
-_Note that this package is still WIP, see [v1 roadmap milestone](https://github.com/viddo/atom-textual-velocity/milestones) for details.  See the [change log](CHANGELOG.md) for what's new._
+# Textual Velocity [![Travis Build Status](http://travis-ci.org/viddo/atom-textual-velocity.png?branch=master)](http://travis-ci.org/viddo/atom-textual-velocity) [![CircleCI Build status](https://circleci.com/gh/viddo/atom-textual-velocity/tree/master.png?style=shield&circle-token=:circle-token)](https://circleci.com/gh/viddo/atom-textual-velocity) [![David dependency management](https://david-dm.org/viddo/atom-textual-velocity.svg)](https://david-dm.org/viddo/atom-textual-velocity)
 
 Your mental notes at your fingertips!
 
-For those of you who used [Notational Velocity](http://notational.net/) or [nvalt](http://brettterpstra.com/projects/nvAlt/) before should feel right at home.
+For those of you who used [Notational Velocity](http://notational.net/) or [nvAlt](http://brettterpstra.com/projects/nvAlt/) should feel right at home: it's intended to be an alternative to those applications but with the benefits of the [Atom](https://atom.io/) ecosystem.
 
 <img width="748" alt="screen shot 2016-02-04 at 20 05 58" src="https://cloud.githubusercontent.com/assets/978461/12831123/f48a5964-cb92-11e5-9752-859edd2ed3a9.png">
 
-## Usage
-The package is lazy-loaded, use the `Textual Velocity: Start Session` [command](https://atom.io/docs/v1.4.3/getting-started-atom-basics#command-palette) to get started.
-
-By default notes are saved in `~/.atom/notes`, you can change it through the `textual-velocity:path` [config](https://atom.io/docs/api/v1.5.0/Config) setting.
+Caveats:
+ - Still WIP, see the [change log](CHANGELOG.md) for what's been done so far, and [v1 roadmap milestone](https://github.com/viddo/atom-textual-velocity/milestones) for planned/upcoming features.
+ - Developed and tested on MacOSX, it _should_ work fine on Linux and Windows too but there's not guarantees right now. Help is appreciated!
+ - Due to Atom's purpose of being a _text_-editor only text files are intended to be supported, compared to the single-database option NV offers.
 
-You may also want to set a global shortcut to toggle the Atom window, see my [init config](docs/init.coffee) for an example of how this can be setup when the package is activated.
+## Usage
+Use the `Textual Velocity: Start Session` [command](https://atom.io/docs/v1.4.3/getting-started-atom-basics#command-palette) to get started, the package is lazy loaded.
 
-The `core.ignoredNames` and `core.excludeVcsIgnoredPaths` are respected, but you need to restart a session for the changes to apply.
+By default notes are saved in `~/.atom/notes`, you can change it in the package settings.
 
-See [keymaps](keymaps/textual-velocity.cson) for available shortcuts.
+While the plugin can be run in any Atom window it's recommended to run it in a [separate instance for easier usage and access to your notes](docs/recommended-usage/README.md)
 
 Also, I recommend the following packages, that works great in combination with textual-velocity:
 - [quick-file-actions](https://atom.io/packages/quick-file-actions) - Quickly copy, delete, move, and create new files
 - [file-icons](https://atom.io/packages/file-icons) - Assign file extension icons and colours for improved visual grepping
 - [preview](https://atom.io/packages/preview) - Ultimate previewer of source code in Atom.
 - [recent-files-fuzzy-finder](https://atom.io/packages/recent-files-fuzzy-finder) - Find recently opened files easier
 - [block-travel](https://atom.io/packages/block-travel) - Quickly travel up/down between blocks of code
-
-## Installation
-`apm install textual-velocity`, or search & install it through the settings.

docs/init.coffee renamed to docs/recommended-usage/.atom/init.coffee

@@ -1,6 +1,4 @@
-# ~/.atom/init.coffee
 # Init script to register global shortcut and hide tree-view when session is started
-
 atom.packages.onDidActivatePackage (pkg) ->
   return if pkg.name isnt 'textual-velocity'
 
@@ -13,20 +11,29 @@ atom.packages.onDidActivatePackage (pkg) ->
   ret = globalShortcut.register keyCombo, ->
     target = document.body.querySelector('atom-workspace')
     atom.commands.dispatch(target, 'textual-velocity:toggle-atom-window')
-  unless ret
+  if ret
+    atom.notifications.addSuccess "Registered #{keyCombo} to toggle this Atom window", {
+      description: ''
+      dismissable: true
+    }
+  else
     atom.notifications.addWarning "Could not register #{keyCombo} as shortcut", {
-      detail: 'Probably already registered by another app or window, try restarted atom completely'
+      description: 'Probably already registered by another app or window, try restarted atom completely'
       dismissable: true
     }
 
-  # Hide tree-view
+  # Hide tree-view when package is activated
   try
     treeView = atom.packages.getActivePackage('tree-view').mainModule.createView()
     if treeView.isVisible()
       treeView.toggle() # i.e. hide it
   catch err
     console.error(err)
     atom.notifications.addWarning 'Could not hide tree view', {
-      detail: 'See the console for the error'
+      description: 'See the console for the error'
       dismissable: true
     }
+
+# Activate package right away
+target = document.body.querySelector('atom-workspace')
+atom.commands.dispatch(target, 'textual-velocity:start-session')

docs/recommended-usage/README.md

@@ -0,0 +1,7 @@
+# Recommended usage
+
+While the plugin can be run in any Atom window it's recommended to run it in a separate instance for easier usage and access to your notes.
+
+The custom init script [.atom/init.coffee](.atom/init.coffee#L10) contains some code to activate this package on startup, and to register a global keyboard shortcut to easily toggle/access the Atom window and this package's search field.
+
+You may of course copy-paste this to your global Atom init config (typically located at `~/.atom/init.coffee`), but otherwise you can check the the shell script [mac-atom-beta.sh](mac-atom-beta.sh) for an example how to run a separate [Atom beta](https://atom.io/beta) instance (assumed to be installed in the default location), which use a custom atom-home dir to run the custom init script only for this instance.

docs/recommended-usage/mac-atom-beta.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -x
+THIS_DIR="$(dirname "$0")"
+cd "$THIS_DIR"
+# custom ATOM_HOME to run the init script located there
+# override user-data-dir due to https://github.com/atom/atom/issues/11806#issuecomment-249862337
+ATOM_HOME="$THIS_DIR/.atom" open "/Applications/Atom Beta.app" --args --user-data-dir ~/Library/Application\ Support/AtomBeta