diff --git a/README.md b/README.md
index b210c02..996fc16 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,7 @@
 # alice
 
-CI framework with support for local running.
\ No newline at end of file
+CI framework with support for local running.
+
+* [Basic usage](alice-ci/README.md)
+* [Runners](docs/runners.md)
+* [CI syntax](docs/syntax.md)
\ No newline at end of file
diff --git a/alice-ci/src/alice/cli.py b/alice-ci/src/alice/cli.py
index ad1d40f..95dd602 100644
--- a/alice-ci/src/alice/cli.py
+++ b/alice-ci/src/alice/cli.py
@@ -78,7 +78,7 @@ def main():
 
     parser = argparse.ArgumentParser()
     parser.add_argument("steps", nargs='+')
-    parser.add_argument("-i", "--input", default="ci.yaml")
+    parser.add_argument("-i", "--input", default="alice-ci.yaml")
     parser.add_argument("-e", "--env", nargs='*', default=[])
     args = parser.parse_args()
     if not os.path.isfile(args.input):
diff --git a/docs/examples.md b/docs/examples.md
new file mode 100644
index 0000000..d181b42
--- /dev/null
+++ b/docs/examples.md
@@ -0,0 +1,24 @@
+# alice-ci.yaml examples
+
+## Python lint
+
+Installes flake8 package in a virtual elvironment, then lints the contents of the packages directory in the current working dir.
+
+```
+runners:
+  python:
+    dependencies:
+      - name: flake8
+jobs:
+  - name: lint
+    type: python
+    workdir: packages
+    commands:
+      - "-m flake8"
+```
+
+To run this job:
+
+```
+pythom3 -m alice lint
+```
\ No newline at end of file
diff --git a/docs/runners.md b/docs/runners.md
new file mode 100644
index 0000000..08a4b8e
--- /dev/null
+++ b/docs/runners.md
@@ -0,0 +1,8 @@
+# Runners
+
+Runners are responsible to execute a list of commands in a set environment defined in the CI yaml file.
+
+## List of runners
+
+* Python - executes python commands in a virtual environment
+* Docker - executes each job in a separate Docker container - unimplemented
\ No newline at end of file
diff --git a/docs/syntax.md b/docs/syntax.md
new file mode 100644
index 0000000..285c1d7
--- /dev/null
+++ b/docs/syntax.md
@@ -0,0 +1,37 @@
+# alice-ci.yaml
+
+This yaml file defines the job steps executed by Alice. The jobs are called by names for each passed parameter on CLI. For example the following command searches for a job called lint defined in the `alice-ci.yaml` file in the current working directory, then runs it.
+
+```
+pythom3 -m alice lint
+```
+
+## runners
+
+Contains global configuration for various runners. Currently the only supported runner is `python`.
+
+### Python
+
+#### Dependencies
+
+List of dependencies installed in the virtual environment. Each dependency has a `name` and an `import_name`, as Alice checks the availability of each package by trying to import `import_name`, and if it fails, calls pip to install `name`.
+
+## jobs
+
+List of jobs. Each job has a mandatory name, type and a list of commands, optional parameter is workdir.
+
+### name
+
+Mandatory value, string. Has to be unique in the current file.
+
+### type
+
+Job type, selects the runner executing the commands. Currently the only supported type is `python`.
+
+### comands
+
+List of strings, each executed one by one from top to bottom in the current context. 
+
+### workdir
+
+Optional, defines Working directory relative to PWD. The default working directory is the current directory.