Merge pull request #6 from mabrasil/master

Better docs organization
mysamai · Oct 24, 2015 · 1402ebd · 1402ebd
2 parents 8ede04b + 30b2830
commit 1402ebd
Show file tree

Hide file tree

Showing 3 changed files with 140 additions and 82 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,29 @@
+# Contributing
+
+## Table of Contents
+
+- [Reporting a bug](#reporting-a-bug)
+- [The 5 magic steps](#the-5-magic-steps)
+- [License](#license)
+
+## Reporting a bug
+
+1. Look for any related issues [here](https://github.com/daffl/mysam/issues).
+2. If you find an issue that seems related, please comment there instead of creating a new issue. If it is determined to be a unique bug, we will let you know that a new issue can be created.
+3. If you find no related issue, create a new issue by clicking [here](https://github.com/daffl/mysam/issues/new).
+If we find an issue that's related, we will reference it and close your issue, showing you where to follow the bug.
+4. Tell us important details like what operating system you are using.
+5. Include any errors that may be displayed.
+6. Update us if you have any new info, or if the problem resolves itself!
+
+##The 5 magic steps
+
+1. Fork it!
+2. Create your feature branch: `git checkout -b my-new-feature`
+3. Commit your changes: `git commit -m 'Add some feature'`
+4. Push to the branch: `git push origin my-new-feature`
+5. Submit a pull request :)
+
+## License
+
+[MySam](https://github.com/daffl/mysam) is distributed under the MIT License, [available in this repository](master/LICENSE.md). All contributions are assumed to be also licensed under the same.
diff --git a/LICENSE → LICENSE.md b/LICENSE → LICENSE.md
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.
diff --git a/readme.md b/readme.md
@@ -1,55 +1,67 @@
-# Say hi SAM
+# Say *hi*, SAM
 
-[ ![Codeship Status for daffl/mysam](https://codeship.com/projects/b26a3f10-3c66-0133-d19d-1276d5d0a1e7/status?branch=master)](https://codeship.com/projects/102258)
+[![Codeship Status for daffl/mysam](https://codeship.com/projects/b26a3f10-3c66-0133-d19d-1276d5d0a1e7/status?branch=master)](https://codeship.com/projects/102258)
 
-Sam is an open-source, web-based "intelligent" assistant. It can listen to you, learn new actions and is extensible with JavaScript plugins. Sam runs a [NodeJS](https://nodejs.org/en/) server and in any modern browser or as an [Electron](http://electron.atom.io/) desktop application.
+> Sam is an open-source, web-based *"intelligent"* assistant. It can listen to you, learn new actions and is extensible with JavaScript plugins. Sam runs a [NodeJS](https://nodejs.org/en/) server and in any modern browser or as an [Electron](http://electron.atom.io/) desktop application.
 
 Watch this video to see what Sam can do:
 
 [![MySam video](http://daffl.github.io/mysam/mysam-video.png)](https://www.youtube.com/watch?v=VxFtSsCM_bo)
 
-# Installation
+## Table of Contents
+
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Using the CLI](#using-the-cli)
+- [Plugins](#plugins)
+  - [Creating Plugins](#creating-plugins)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
 
 Install Sam globally with:
 
-> npm install mysam -g
+`$ npm install mysam -g`
 
 And then run either the desktop application with:
 
-> mysam
+`$ mysam`
 
 Or the server only (which will be available at [localhost:9090](http://localhost:9090)) via:
 
-> mysam --server
+`$ mysam --server`
 
-# Getting started
+## Getting Started
 
 At first startup Sam will load the basic frontend training data (like learning your name, provide help, saying hi or to learn something new) and ask for your name.
 
 To talk to Sam press *CTRL + SPACE* (make sure the window is focused).
 
 All inputs can be submitted with *CTRL + ENTER* (when not in a textarea).
 
-# Plugins
+## Using the CLI
 
-All plugins are available on NPM. To ask Sam about the weather run:
+The following command line options are available:
 
-> npm install mysam-weather -g
+|       Flags       |        Description        |
+|-------------------|---------------------------|
+| `-s`, `--server`  | Start server mode only    |
+| `-d`, `--develop` | Start in development mode |
 
-Then restart the application and ask something like
+Development mode (`--develop`) will load the development tools in the Electron application, output detailed log messages to the command line and load the frontend in individual modules. This is helpful when creating your own plugins.
 
-> What's the weather in Berlin?
+## Plugins
 
-# Using the CLI
+All plugins are available on NPM. To ask Sam about the weather run:
 
-The following command line options are available:
+`$ npm install mysam-weather -g`
 
-- __-s, --server__ - Start server mode only
-- __-d, --develop__ - Start in development mode
+Then restart the application and ask something like
 
-Development mode (`--develop`) will load the development tools in the Electron application, output detailed log messages to the command line and load the frontend in individual modules. This is helpful when creating your own plugins.
+> What's the weather in Berlin?
 
-# Creating plugins
+### Creating Plugins
 
 To create a new plugin create a new folder with the following `package.json`:
 
@@ -60,79 +72,96 @@ To create a new plugin create a new folder with the following `package.json`:
   "mysam": {
     "client": "frontend",
     "styles": "styles.css"
-  }
+  },
+  "keywords": [
+    "mysam-plugin"
+  ]
 }
 ```
-
-In the same folder a `server.js` like this:
-
-```js
-module.exports = function(sam) {
-  // on the server, `sam` is a Feathers application so
-  // for example we can create new actions like this:
-  sam.service('actions').create({
-    text: 'Ping from my plugin',
-    tags: [],
-    action: {
-      type: 'myplugin',
-      ping: 'Default ping'
-    }
-  }, function(error, data) {
-    console.log('Created', data);
-  });
-};
-```
-
-And a `frontend.js` like this:
-
-```js
-module.exports = function(sam) {
-  // sam is the client side application instance
-  // which you can register new actions like this:
-  sam.action('myplugin', function(element, classification) {
-    // element is the jQuery wrapped main element
-    // classification is an object with information about the
-    // text that triggered this action
-    var heading = document.createElement('h1');
-    heading.className = 'myplugin';
-    heading.innerHTML = 'Hello from my plugin: ' + classification.action.ping;
-
-    element.html(heading);
-  });
-
-  // and learners (which will also show up in the help) like this
-  sam.learn({
-    description: 'Call myplugin',
-    tags: ['name'],
-    form: function(el, save) {
-      el.html('<input type="text" class="param" />')
-        .on('submit', function(save) {
-          save({
-            type: 'myplugin',
-            ping: el.find('.param').val()
+> **Note**: It is important to add the `mysam-plugin` keyword to your `package.json`
+file to ensure that your plugin will be shown in *MySam*'s plugins catalog.
+
+- In the same folder a `server.js` like this:
+
+  ```js
+  module.exports = function(sam) {
+    // on the server, `sam` is a Feathers application so
+    // for example we can create new actions like this:
+    sam.service('actions').create({
+      text: 'Ping from my plugin',
+      tags: [],
+      action: {
+        type: 'myplugin',
+        ping: 'Default ping'
+      }
+    }, function(error, data) {
+      console.log('Created', data);
+    });
+  };
+  ```
+
+- And a `frontend.js` like this:
+
+  ```js
+  module.exports = function(sam) {
+    // sam is the client side application instance
+    // which you can register new actions like this:
+    sam.action('myplugin', function(element, classification) {
+      // element is the jQuery wrapped main element
+      // classification is an object with information about the
+      // text that triggered this action
+      var heading = document.createElement('h1');
+      heading.className = 'myplugin';
+      heading.innerHTML = 'Hello from my plugin: ' + classification.action.ping;
+
+      element.html(heading);
+    });
+
+    // and learners (which will also show up in the help) like this
+    sam.learn({
+      description: 'Call myplugin',
+      tags: ['name'],
+      form: function(el, save) {
+        el.html('<input type="text" class="param" />')
+          .on('submit', function(save) {
+            save({
+              type: 'myplugin',
+              ping: el.find('.param').val()
+            });
           });
-        });
-    }
-  });
-};
-```
+      }
+    });
+  };
+  ```
 
-`styles.css` can contain any CSS styles:
+- `styles.css` can contain any CSS styles:
 
-```css
-.myplugin {
-  font-size: 4em;
-}
-```
+  ```css
+  .myplugin {
+    font-size: 4em;
+  }
+  ```
+
+> You'll soon have a [Yeoman](http://yeoman.io/) generator for new plugins
+that initialize everything similar to what is described above so that you can
+just do `$ mysam create my-plugin`.
 
 To use the plugin run
 
-> npm link
+`$ npm link`
 
 in the plugin folder and restart the application (for easier debugging you can use the `--develop` flag).
 
-Now saying something like
+Now saying something like:
 
-> Can I get a ping from my plugin please?
+> *Can I get a ping from my plugin please?*
 
 Should show the element we created in the action.
+
+## Contributing
+
+Contributions are very welcome! If you'd like to contribute, these [guidelines](CONTRIBUTING.md) may help you.
+
+## License
+
+[MySam](https://github.com/daffl/mysam) is distributed under the MIT License, [available in this repository](master/LICENSE.md). All contributions are assumed to be also licensed under the same.