1 files changed, 108 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5d1a510
--- /dev/null
+++ b/README.md
@@ -0,0 +1,108 @@
+Overview
+========
+
+This application allows to apply Elo-like rankings to Formula One races.
+
+Requirements
+============
+
+ * python 2.x (developed and tested on 2.7.8)
+ * SQLAlchemy
+ * PySQLite (optional)
+ * MySQL connector for python (optional)
+ * dateutil
+
+Import scripts use some additional libraries, such as:
+
+ * BeautifulSoup4
+ * lxml
+ * urllib, urllib2, urlparse
+
+You can use the application with either SQLite database or MySQL database (in that case you, well, need a MySQL database).
+
+Installation
+============
+
+1. Fetch this repository
+2. Configure your database (see: Configuration:Database)
+3. Fill the database with result data
+4. All done!
+
+Usage
+=====
+```
+usage: elo.py [-h] [--date DATE] [--limit LIMIT] [-v] [--force] [COMMAND]
+
+positional arguments:
+  COMMAND        Action to execute against the database:
+                 print - prints the rankings for all drivers ranked in 12 months,
+                 reset - resets the rankings,
+                 rate - calculates the rankings
+                 init - init clean database for the application
+                 Default value is 'print'.
+
+optional arguments:
+  -h, --help     show this help message and exit
+  --date DATE    Date for which the action should be executed.
+                 Print ratings for DATE,
+                 reset ratings all the way down to DATE
+                 or rank the races all the way up to DATE.
+  --limit LIMIT  Ranking list (display) cut-off point.
+  -v             Display verbose info on rating progress to STDERR.
+  --force, -f    Force database initialization (for "init" command).
+```
+
+Configuration
+=============
+
+Application configuration consists of two JSON-formatted files: elo.json and db.json.
+
+Database
+--------
+
+`db.json` holds database configuration. Two example files (for both MySQL and SQLite) are provided. If you want a quick-start solution, just rename the `db.json.SQLITE-EXAMPLE` to `db.json`.
+
+The first time you run the application against a fresh database, you have to initialize the structure, by running:
+
+    ./elo.py init
+
+At any time, you can do a hard reset on the existing database, by running init with `--force` parameter. This truncates all the data, including race results data from the database, and recreates the structure.
+
+Results data are provided in elo.db pre-filled SQLite database or in sql/results.sql, in plain SQL format.
+
+Elo parameters
+--------------
+
+`elo.json` contains algorithm parameter for Elo ratings:
+
+ * initial driver ranking
+ * algorithm disparity options
+ * algorithm importance for distinct race types (championship/non-championship, qualifying/race)
+ * algorithm importance thresholds
+
+Remember that any change to parameters should lead to ranking reset (`./elo.py reset; ./elo.py rate`) if you want consistent rating criteria throughout the entires time span of results database.
+
+More information
+================
+
+More elaborate write-up of the methodology and general approach to the problem can be found in the doc/ directory of source code repository, which contains:
+
+ * races.md: explanation of race selection for the results database
+ * results.md: summary of the scoring method
+ * sources.md: summary of sources used for result data
+ * challenges.md: two most dificult aspects of the project, described in detail
+ * sql.md: useful or interesting queries to be run against the database (may only be applicable to the MySQL database)
+
+Author
+======
+
+If you want to contact me about the application, you can drop me a private message on Reddit: /u/emkael (although I know it's not exactly rocket science to work out other means of communication, from the GitHub account alone). I'll do my best to help.
+
+License
+=======
+
+lol, idk.
+
+Do: use it, share it, mix it, modify it, analyse it - just leave some attribution.
+
+Don't: sell it?