adding docs

README.md

@@ -0,0 +1 @@
+This is a toy configuration language.  If you want to know why, see the [WHY](WHY.md) doc.

WHY.md

@@ -0,0 +1,86 @@
+### Why?
+
+Quite often in the course of writing Go programs I've found myself in need of a
+format to describe the application's configuration.  The only formats in the Go
+standard library are json and xml.
+
+#### Why not XML?
+
+xml is fairly verbose and doesn't map to data structures particularly well.
+There are many ways of expressing the same thing.  E.g., what's the difference
+between this:
+
+```
+<person>
+    <first_name>jordan</first_name>
+    <last_name>orelli</last_name>
+</person>
+```
+
+and this:  `<person first_name="jordan" last_name="orelli" />`?
+
+There are also spurious type indicators.  What do you do if you just want an
+array of integers?
+
+```
+<sizes>
+    <size>1</size>
+    <size>3</size>
+    <size>8</size>
+</sizes>
+```
+
+In reality, all I want for that is something like `sizes: [1 3 8]`.
+
+On top of the combination ambiguity and verbosity of the language itself, the
+xml package in the Go standard library is cumbersome to work with.  The few
+times I've tried it, it didn't strike me as being a particularly pleasurable
+programming model.  It's not particularly well-suited to the task of writing
+the host application, and it's not particularly well-suited to the task of
+writing the config files themselves.
+
+#### Why not JSON?
+
+Historically, I have always used json as the configuration format for Go
+projects.  I've found this to be the best option.  It's in the standard
+library, so it doesn't add any dependencies to your project.  Everyone can
+understand it, and those that don't pick it up very quickly.  It's a nearly
+ideal format, inasmuch as it doesn't litter itself with spurious information,
+it's relatively compact, and it's a familiar set of non-word characters that
+everyone can grok.  The parsing API is also quite nice, and the json package in
+the standard library is extremely easy to use.  As far as programming the host
+application, json works very well.
+
+But over time, using json gets worse and worse.  When it comes to authoring
+json config files, things are a little less rosey.  At first it seems fine,
+when your configs are small and your projects are simple.  Over time, as the
+projects get more complex and you require more configuration, the files become
+challenging to read and edit.  It's exceptionally easy to introduce syntax
+errors into json documents.  Object keys seem to require double-quotes for no
+reason at all.  There are no comments.  You're more or less pidgeonholed into
+making your whole configuration file one object, because if you don't, you wind
+up complicating the parsing API for the host application, and it becomes
+difficult to program, which was one of the best features of using json to begin
+with.  Then there are the weird things, like the fact that re-declaring a key
+in an object just overwrites the previous value
+([ex](http://play.golang.org/p/ky4F9UmM1Z)), which fundamentally makes no
+sense because objects are supposed to be order-independent but in reality
+they're not.  As far as performing automated validations, json doesn't give you
+much help.
+
+It also seems to drive my colleagues in ops into an absolute rage.
+
+#### Why not YAML?
+
+Every time I use YAML I accidentally break it.  It's incredibly brittle.  I
+actually do buy the argument that semantic whitespace is great for humans.  I
+programmed a significant amount of Python and loved every minute of it.
+
+But where it really breaks down is that semantic whitespace is an absolute
+showstopper when it comes to generating a configuration file from a template
+system, which is a common technique in
+[Chef](http://en.wikipedia.org/wiki/Chef_%28software%29), the configuration
+management tool we use [where I work](https://www.etsy.com/).  Beyond being
+impossible to template out, it's much, much too complicated.  The YAML spec is
+nearly as large as the specification for Go itself!
+