--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/HACKING.md	Mon Jan 20 16:32:20 2014 -0500
@@ -0,0 +1,64 @@
+HACKING
+=======
+This document describes the design, structure and conventions used in the
+project.
+
+Lots of places in the documentation will use `c.r.t.t.e` as a
+package/module/directory name. This is just a short form of
+`com.redhat.thermostat.tools.eclipse`.
+
+Building from Source
+--------------------
+Use maven to build:
+
+    mvn clean verify
+
+There's no need to `install` anything.
+
+
+Maven vs Tycho
+--------------
+Under the hood, [tycho][1] is used to build. tycho uses a manifest-first
+approach to build projects (instead of maven's pom-first), so if you are used
+to the maven conventions, you may be a little confused. Information that is
+normally found in a `pom.xml` is spread out across `pom.xml`,
+`META-INF/MANIFEST.MF`, `plugin.xml` and `build.properties` files.
+
+
+Editing Environment
+-------------------
+As an eclipse plugin, it's probably simples to work on this using eclipse.
+Eclipse provides a graphical UI over `META-INF/MANIFEST.MF`, `plugin.xml` and
+`build.properties` files.
+
+Layout
+------
+The root source directory contains the following directories.
+
+ - c.r.t.t.e.plugin
+   This contains the main implementation of the plugin.
+
+ - c.r.t.t.e.plugin-feature
+   This directory contains an eclipse *feature* for the project.
+
+ - c.r.t.t.e.plugin-p2-repo
+   This directory contains code to generate a repository which can be used to
+   install the plugin when it's built.
+
+ - c.r.t.t.e.plugin.tests
+   This directory contains (unit) tests for the plugin. Code here is run on
+   every build. This code is only used at build time and not used to populate
+   the repository.
+
+Tests
+-----
+It's a good idea to add a unit test for every new class introduced.
+
+The convention is that every class in module/package `c.r.t.t.e.plugin` will
+have a corresponding test in module/package `c.r.t.t.e.plugin.tests` with the
+name `<ClassBeingTested>Test.java`. Subpackges of `c.r.t.t.e.plguin` will have
+tests in the corresponding package under`c.r.t.t.e.plugin.tests` (eg:
+`c.r.t.t.e.plugin.foobar` will have tests under
+`c.r.t.t.e.pluing.tests.foobar`).
+
+[1] http://eclipse.org/tycho/

--- a/README.md	Mon Jan 20 16:30:31 2014 -0500
+++ b/README.md	Mon Jan 20 16:32:20 2014 -0500
@@ -56,7 +56,8 @@
 Contributing
 ------------
 
-Please see [TODO.md](TODO.md) for a list of tasks that need doing.
+Please see [HACKING.md](HACKING.md) for code structure, conventions and style.
+[TODO.md](TODO.md) contains a list of tasks that need doing.
 
 [1]: http://eclipse.org