diff --git a/.gitignore b/.gitignore
index daf71622..1bb0923c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,6 +2,9 @@
 #build folder
 build/
 
+#markdown preview output
+README.html
+
 #autogenerated project files
 .cproject
 .mxproject
diff --git a/README.md b/README.md
index acc5c62b..10708739 100644
--- a/README.md
+++ b/README.md
@@ -1,23 +1,72 @@
 
-### Compiling the firmware
-#### Installing prerequisites 
+### Table of contents
+
+<!-- MarkdownTOC depth=2 autolink=true bracket=round -->
+
+- [Compiling and downloading firmware](#compiling-and-downloading-firmware)
+- [Generating startup code](#generating-startup-code)
+- [Setting up Eclipse development environment](#setting-up-eclipse-development-environment)
+
+<!-- /MarkdownTOC -->
+
+
+## Compiling and downloading firmware
+
+### Getting a programmer
+Get a programmer that supports SWD (Serial Wire Debugging) and is ST-link v2 compatible. You can get them really cheap on [eBay](http://www.ebay.co.uk/itm/ST-Link-V2-Emulator-Downloader-Programming-Mini-Unit-STM8-STM32-with-20CM-Line-/391173940927?hash=item5b13c8a6bf:g:3g8AAOSw~OdVf-Tu) or many other places.
+
+### Installing prerequisites 
 To compile the program, you first need to install the prerequisite tools:
-* `gcc-arm-none-eabi`: GCC compilation toolchain for ARM microcontrollers.
-  * Installing on Ubuntu: `sudo apt-get install gcc-arm-none-eabi`
-* `stm32cubeMX`: Tool from STM to automatically generate setup routines and configure libraries, etc.
-  * Available [here](http://www2.st.com/content/st_com/en/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-configurators-and-code-generators/stm32cubemx.html?icmp=stm32cubemx_pron_pr-stm32cubef2_apr2014&sc=stm32cube-pr2)
 
-#### Generate code
+* `gcc-arm-none-eabi`: GCC compilation toolchain for ARM microcontrollers.
+    * Installing on Ubuntu: `sudo apt-get install gcc-arm-none-eabi`
+    * Installing on Windows (Cygwin): TODO
+* `OpenOCD`: Open On-Chip Debugging tools. This is what we use to flash the code onto the microcontroller.
+    * Installing on Ubuntu: `sudo apt-get install openocd`
+    * Installing on Windows (Cygwin): TODO
+
+### Building the firmware
+Run `make` in the root of this repository.
+
+### Flashing the firmware
+Connect `SWD`, `SWC`, and `GND` on connector J2 to the programmer.
+You need to power the board by only **ONE** of the following: VCC(3.3v), 5V, or the main power connection (the DC bus). The USB port (J1) does not power the board.
+Run `make flash` in the root of this repository.
+(TODO Currently not implemented yet.)
+
+
+## Generating startup code
+**Note:** You do not need to run this step to program the board. This is only required if you wish to update the auto generated code.
+
+This project uses the STM32CubeMX tool to generate startup code and to ease the configuration of the peripherals.
+We also use a tool to generate the Makefile. The steps to do this are as follows.
+
+### Installing prerequisites
+* `stm32cubeMX`: Tool from STM to automatically generate setup routines and configure libraries, etc.
+    * Available [here](http://www2.st.com/content/st_com/en/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-configurators-and-code-generators/stm32cubemx.html?icmp=stm32cubemx_pron_pr-stm32cubef2_apr2014&sc=stm32cube-pr2)
+
+### Generate code
 * Run stm32cubeMX and load the `stm32cubemx/Odrive.ioc` project file.
 * Press `Project -> Generate code`
 * You may need to let it download some drivers and such.
 
-#### Generate makefile
+### Generate makefile
 There is an excellent project called CubeMX2Makefile, originally from baoshi. This project is included as a submodule.
-* Initalise and clone the submodules: `git submodule init; git submodule update`
-* Generate makefile: `CubeMX2Makefile/CubeMX2Makefile.py stm32cubemx/`
-* Try to build the stuff!
-```sh
-cd stm32cubemx
-make
-```
+* Initialise and clone the submodules: `git submodule init; git submodule update`
+* Generate makefile: `CubeMX2Makefile/CubeMX2Makefile.py .`
+
+
+## Setting up Eclipse development environment
+
+### Install
+* Install [Eclipse IDE for C/C++ Developers](http://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/mars2)
+* Install the [OpenOCD Eclipse plugin](http://gnuarmeclipse.github.io/plugins/install/)
+
+### Import project
+* File -> Import -> C/C++ -> Existing Code as Makefile Project
+* Browse for existing code location, find the OdriveFirmware root.
+* In the Toolchain options, select `Cross GCC`
+* Hit Finish
+
+###
+
diff --git a/screenshots/CodeAsMakefile.png b/screenshots/CodeAsMakefile.png
new file mode 100644
index 00000000..5d846bda
Binary files /dev/null and b/screenshots/CodeAsMakefile.png differ