Update the README and add some markdown

2 files changed, 44 insertions, 15 deletions

diff --git a/README b/README
deleted file mode 100644
index 0cca129..0000000
--- a/README
+++ /dev/null
@@ -1,15 +0,0 @@
-Classes present in this repository are dummies, and should fully implement
-the expected API that'll be used in Settings. 
-
-Each device should implement its own classes for supported hardware 
-tunables, and signal their existence by adding a BOARD_HARDWARE_CLASS 
-variable to its BoardConfig, pointing to the path where said classes
-can be found. The Nexus4, for instance, has
-
-BOARD_HARDWARE_CLASS := device/lge/mako/cmhw/
-
-Every class present in this framework addresses a hardware tunable;
-Devices don't need to implement all the classes, but for every one
-that _is_ implemented, all methods existing in this dummy implementation
-must be present.
-
diff --git a/README.mkdn b/README.mkdn
new file mode 100644
index 0000000..2dd38bf
--- /dev/null
+++ b/README.mkdn
@@ -0,0 +1,44 @@
+CyanogenMod Hardware Abstraction Framework
+==========================================
+
+What's this?
+------------
+
+It's a simple library with a set of classes to access hardware tunables
+and properties that tend to vary from platform to platform, or device to
+device, but are still useful to present functionality to the end user.
+Examples of these tunables are display color calibration, processor eco
+modes, vibration strength, sensor reset/recalibrate, etc.
+
+The library should present a common interface and completely abstract
+implementation details so that the UI part of said functionality (the
+knobs and buttons users actually interact with) can be implemented at
+a single location on any shipped platform app (typically, Settings). No
+UI or layout elements should be included in here.
+
+How do I use it?
+----------------
+
+Classes present in this repository are dummies, and should fully implement
+the expected API that'll be used in Settings. 
+
+Each device should implement its own classes for supported hardware 
+tunables, and signal their existence by adding a BOARD_HARDWARE_CLASS 
+variable to its BoardConfig, pointing to the path where said classes
+can be found. The Nexus4, for instance, has
+
+BOARD_HARDWARE_CLASS := device/lge/mako/cmhw/
+
+Every class present in this framework addresses a single tunable;
+Devices don't need to implement all the classes, but for every one
+that _is_ implemented, all methods existing in this dummy implementation
+must be present, since the client applications will expect them to
+be there.
+
+Wouldn't it be better if...?
+----------------------------
+
+There are reasons for this not to be implemented as an interface definition,
+or a set of superclasses. Fully overloading the reference class isn't pretty,
+but at this point it's the most flexible option we have, especially since
+we still haven't fully closed what we're going to put in here.