Index: docs/source/index.rst
===================================================================
--- docs/source/index.rst
+++ docs/source/index.rst
@@ -36,6 +36,7 @@
    devguide
    writing_tasks
    library
+   taskyaml
 
 
 Indices and tables
Index: docs/source/taskyaml.rst
===================================================================
--- /dev/null
+++ docs/source/taskyaml.rst
@@ -0,0 +1,169 @@
+==========================
+Taskotron Task YAML Format
+==========================
+
+One of the core bits of Taskotron is the yaml file used to describe tasks to be
+run. As Taskotron is still a very young project, some components of the task yaml
+files are not yet used by the task runner but are useful to human readers of
+the task. Those sections will be noted and those notes updated as things change.
+
+The documentation here is a description of how things are implemented but are
+a little light on the practical creation of tasks. **link to task creation howto**
+and some existing tasks are also good references:
+
+  * `rpmlint <https://bitbucket.org/fedoraqa/task-rpmlint>`_
+  * `examplebodhi <https://bitbucket.org/fedoraqa/task-examplebodhi>`_
+
+Task Description
+================
+
+Metadata
+--------
+
+Some metadata is required to be in the task yaml file:
+
+  * task name
+  * description
+  * maintainer
+
+.. code-block:: yaml
+
+  ---
+  name: rpmlint
+  desc: download specified rpms and run rpmlint on them
+  maintainer: tflink
+
+.. note::
+
+  Please use a FAS account name for the maintainer
+
+
+Input
+-----
+
+Most tasks require some form of input. The required input must be declared in
+order to verify that the task can be run
+
+.. code-block:: yaml
+
+  input:
+      args: arch, envr
+
+Valid args include:
+
+  * arch
+  * envr
+  * bodhi_id
+  * koji_tag
+
+Dependencies
+------------
+
+A task may also require the presence of other code to support execution. Those
+dependencies are specified as part of the environment description.
+
+.. code-block:: yaml
+
+  environment:
+      rpm:
+          - rpmlint
+          - libtaskotron
+
+.. note::
+
+  At this time, the list of rpm dependencies is not checked during execution
+  but this will change in future versions. For now, this section is ignored and
+  is mostly for human reference.
+
+.. note::
+
+  Future versions will also support specifying dependencies in other formats
+  than RPM.
+
+
+Task Execution
+==============
+
+Every task is defined in the `task` block of the task yaml file. The task
+consists of one or more steps which consist of a name, directive and optional
+export of data.
+
+.. code-block:: yaml
+
+  task:
+      - name: using directivename for something
+        directivename:
+            arg1: value1
+            arg2: "{{ some_variable }}"
+        export: somestep_output
+
+
+Variable Storage and Syntax
+---------------------------
+
+The task yaml file uses standard `jinja2 <http://jinja.pocoo.org/>`_ syntax for
+variables. Variables can be created during task execution or provided by default
+by the task runner.
+
+.. note::
+
+  An unfortunate side-effect of using jinja2 syntax with yaml files is that the
+  yaml parser tends to view variables as invalid dictionaries. If the variable
+  is directly following a colon, make sure to surround it in quotes so that the
+  yaml parser interprets the variable as a string.
+
+  .. code-block:: yaml
+
+    # this will not parse well
+    arg1: {{ some_variable }}
+
+    # this will parse properly
+    arg1: "{{ some_variable }}"
+
+Provided Variables
+------------------
+
+The task runner provides the following variables without a need for them to be
+explicitly specified:
+
+  * workdir
+  * jobid
+
+.. note::
+
+  The `jobid` is used primarially for reporting to render proper log and job
+  urls. It can be specified on the command line but isn't required for local
+  execution. If a `jobid` is not explicitly provided at execution time, a
+  sane default value will be provided by the runner.
+
+Created Variables
+-----------------
+
+There are many situations in which the output from one step is used as input
+for another step which is executed later. In order for a step's output to be
+used later, it must first be exported.
+
+.. code-block:: yaml
+
+  task:
+      - name: first step
+        directive_one:
+            arg1: value1
+        export: firststep_output
+
+      - name: second step
+        directive_two:
+            arg1: "{{ firststep_output }}"
+
+In this example, the output from `first step` is stored as `firststep_output`
+and later used by `second step`. Once the `first step` is executed, its
+output is stored as a variable using the name following `export:`.
+
+
+Directives
+==========
+
+The directives which are used in task steps are defined in libtaskotron. These
+directives are grouped into three types: preparation, execution and reporting.
+
+**Needs some sort of link or list of directives and their documentation**
