Update project documentation

We need detailed instructions for other people to use this package and
contribute to the project.

This should make it clearer for new devs what is going on in the code
and it should give people directions about where to start looking at the
codebase.
There is also references to Emacs Lisp learning material.

CONTRIBUTING.md

@@ -1,7 +1,80 @@
+# Project structure
+Currently, all the implementation code is in `projectile-phoenix.el`. The file is separated into the external functions (as of this moment, just the navigation functions) and the utility functions.
+
+The functions named like `projectile-phoenix--this` are intended as private functions. The end-user should not call them, despite Emacs showing them in the function list when calling `describe-function`, for example. The external API for the package is noted as the external functions in the file.
+
+To write tests, we can only check what is returned by the auxiliary functions, since most external functions deal with side effects: opening new buffers, running processes and so on.
+
 ## Dependencies
 This project uses [Buttercup](https://github.com/jorgenschaefer/emacs-buttercup/) for implementing behavior-driven tests and [Cask](https://github.com/cask/cask) for dependency management.
 
-## How to run tests
+## Elisp References
+If you are new to Emacs Lisp, we recommend going through the `GNU Emacs Lisp Reference Manual` (`M-x info` then search for `Emacs Lisp Intro`) and later consulting the `Emacs Lisp Reference Manual` (`M-x info` then search for `Elisp`).
+This project makes heavy use of file-related functions.
+
+## Glossary
+A `resource` is a component of a Phoenix project.
+Examples: controllers, views, templates, routers, migrations.
+
+We define `web resources` as resources that are under the `<project_name>_web`
+directory:
+
+- Controllers
+- Views
+- Routers
+- Channels
+- Templates
+
+For example, if we have a project structure like this:
+
+``` shell
+# ...
+|-- lib
+|   |-- sample_project
+|   |   |-- application.ex
+|   |   `-- repo.ex
+|   |-- sample_project.ex
+|   |-- sample_project_web
+|   |   |-- channels
+|   |   |   `-- user_socket.ex
+|   |   |-- controllers
+|   |   |   `-- page_controller.ex
+|   |   |-- endpoint.ex
+|   |   |-- gettext.ex
+|   |   |-- router.ex
+|   |   |-- templates
+|   |   |   |-- layout
+|   |   |   |   `-- app.html.eex
+|   |   |   `-- page
+|   |   |       `-- index.html.eex
+|   |   `-- views
+|   |       |-- error_helpers.ex
+|   |       |-- error_view.ex
+|   |       |-- layout_view.ex
+|   |       `-- page_view.ex
+|   `-- sample_project_web.ex
+|-- mix.exs
+|-- mix.lock
+|-- priv
+|   |-- gettext
+|   |   |-- en
+|   |   |   `-- LC_MESSAGES
+|   |   |       `-- errors.po
+|   |   `-- errors.pot
+|   |-- repo
+|   |   |-- migrations
+|   |   `-- seeds.exs
+# ...
+```
+
+The controller would be `page_controller.ex`, the views would be `error_view.ex`, `layout_view.ex` and `page_view.ex`, the templates would be `app.html.eex` and `index.html.eex`, the channel is `user_socket.ex` and the router is `router.ex`.
+
+A `private resource` is defined as a resource under the `priv` directory. This includes:
+- Migrations
+- Translation files
+
+# Tests
+## How to run
 Go to the root of the project and run `make test`. This should run Buttercup for you even if you've just cloned the project:
 
 ``` shell

README.md

@@ -1,16 +1,74 @@
 # Projectile-phoenix
+This project is inspired by [Projectile Rails](https://github.com/asok/projectile-rails) and takes some extra code from [Projectile](https://github.com/bbatsov/projectile).
+This is also an early alpha version, so expect a couple bugs.
+For now the package implements navigation between some Phoenix resources.
 
-<!-- Cool image goes here -->
+## Problem proposition
+The reason this package came to be was:
+
+- I started working with Phoenix projects
+- I liked the experience that I had in [Projectile Rails](https://github.com/asok/projectile-rails)
+- There were no similar minor modes for working with Phoenix projects.
+  While Alchemist has `alchemist-phoenix-mode`, the last version covers the
+  previous version of Phoenix, with a different project structure.
+  To update `alchemist` would require more work to get around the code, and that package does a lot of stuff already.
+
+I wanted something that concerns itself only with Phoenix projects, and nothing else.
+So we're going to delegate whatever auxiliary features we can to other projects, such as `alchemist` itself for `alchemist-iex-mode`, `mix`-related stuff to `mix.el` and so on.
 
 This project aims to offer quicker navigation to Phoenix-related files at first:
 
 - [X] Find controller
 - [X] Find view
 - [X] Find template
-- Jump to test
+- [X] Jump to test
 - Run mix tasks
 
-The idea is to have a single navigation responsibility, offloading other features to other packages.
-
 ## Why not use Alchemist?
 Alchemist offers navigation between Phoenix files with a minor mode, but it has been unmaintained for some time now.
+
+## Installation
+This package is not in MELPA yet, so you need to clone this repository into your local machine:
+
+``` shell
+$ git clone git@github.com:Auralcat/projectile-phoenix.git
+```
+
+In your Emacs configuration (usually `init.el`), include this snippet:
+
+``` emacs-lisp
+;; Location of the cloned repository, in this example it is ~/projectile-phoenix
+(add-to-list 'load-path "~/projectile-phoenix")
+(require "projectile-phoenix")
+```
+## Configuration
+To use the package's functions through keybindings, you need to provide a prefix binding in your `init.el` like so.
+This example uses "C-c .", but you're free to use any other chord you like.
+``` emacs-lisp
+(define-key projectile-phoenix-mode-map (kbd "C-c .") 'projectile-phoenix-command-map)
+```
+
+As an alternative, if you use [evil-mode](https://github.com/emacs-evil/evil) and [evil-leader](https://github.com/emacs-evil/evil), you can set a binding to `projectile-phoenix-command-map` directly like this:
+``` emacs-lisp
+(evil-leader/set-key-for-mode 'elixir-mode "." 'projectile-phoenix-command-map)
+```
+
+To activate `projectile-phoenix-mode` automatically for Phoenix projects, include this in your `init.el`:
+``` emacs-lisp
+(projectile-phoenix-global-mode)
+```
+
+## Usage
+When inside a Phoenix project, press the key prefix that you configured and select a function:
+| Function        | Key |
+| Find controller | c   |
+| Find migration  | n   |
+| Find mix task   | m    |
+| Find seed file  | s   |
+| Find template   | l   |
+| Find test       | t   |
+| Find view       | v   |
+
+## Contributing
+For detailed instructions about how the code is structured and project goals, please check `CONTRIBUTING.md`.
+If you've found a bug or want to suggest new features, please open an issue in this repository, and thank you in advance! 💜