Update dev docs

- Import and edit James's API docs into CONTRIBUTING.rst
- Linke correctly to CONTRIBUTING from the main README

CONTRIBUTING.rst

@@ -27,6 +27,83 @@ The following tools are there to help you:
 
 .. _installing dependencies and setting up Let's Encrypt: https://letsencrypt.readthedocs.org/en/latest/using.html
 
+CODE COMPONENTS AND LAYOUT
+==========================
+
+letsencrypt/acme - contains all protocol specific code
+letsencrypt/client - all client code
+letsencrypt/scripts - just the starting point of the code, main.py
+
+Plugin-architecture
+-------------------
+
+Let's Encrypt has a plugin architecture to facilitate support for different
+webservers, other TLS servers, and operating systems.
+
+The most common kind of plugin is a "Configurator", which is likely to
+implement the "Authenticator" and "Installer" interfaces (though some
+Configurators may implement just one of those).
+
+Defined here:
+https://github.com/letsencrypt/lets-encrypt-preview/blob/master/letsencrypt/client/interfaces.py
+
+There are also "Display" plugins, which implement bindings to alternative UI
+libraries.
+
+Authenticators
+--------------
+
+Authenticators are plugins designed to solve challenges received from the
+ACME server. From the protocol, there are essentially two different types
+of challenges. Challenges that must be solved by individual plugins in
+order to satisfy domain validation (dvsni, simpleHttps, dns) and client
+specific challenges (recoveryToken, recoveryContact, pop). Client specific
+challenges are always handled by the "Authenticator"
+client_authenticator.py. Right now we have two DV Authenticators,
+apache/configurator.py and the standalone_authenticator.py. The Standalone
+and Apache authenticators only solve the DVSNI challenge currently. (You
+can set which challenges your authenticator can handle through the
+get_chall_pref(domain) function)
+
+(FYI: We also have a partial implementation for a dns_authenticator in a
+separate branch).
+
+Challenge types are defined here...
+(
+https://github.com/letsencrypt/lets-encrypt-preview/blob/master/letsencrypt/client/constants.py#L16
+)
+
+Installer
+---------
+
+Installers classes exist to actually setup the certificate and be able
+to enhance the configuration. (Turn on HSTS, redirect to HTTPS, etc). You
+can indicate your abilities through the supported_enhancements call. We
+currently only have one Installer written (still developing),
+apache/configurator.py
+
+Installers and Authenticators will oftentimes be the same class/object.
+Installers and Authenticators are kept separate because it should be
+possible to use the standalone_authenticator (it sets up its own Python
+server to perform challenges) with a program that cannot solve challenges
+itself. (I am imagining MTA installers).
+
+*Display* - we currently offer a pythondialog and "text" mode for
+displays. I have rewritten the interface which should be merged within the
+next day (the rewrite is in the revoker branch of the repo and should be
+merged within the next day)
+
+Here is what the display interface will look like
+https://github.com/letsencrypt/lets-encrypt-preview/blob/revoker/letsencrypt/client/interfaces.py#L217
+
+Augeus
+------
+
+Some plugins, especially those designed to reconfigure UNIX servers, can take
+inherit from the augeus_configurator.py class in order to more efficiently
+handle common operations on UNIX server configuration files.
+
+
 .. _coding-style:
 Coding style
 ============

README.rst

@@ -80,7 +80,7 @@ Documentation: https://letsencrypt.readthedocs.org/
 
 Software project: https://github.com/letsencrypt/lets-encrypt-preview
 
-Notes for developers: [CONTRIBUTING.rst](/CONTRIBUTING.rst)
+Notes for developers: CONTRIBUTING.rst_
 
 Main Website: https://letsencrypt.org/
 
@@ -91,3 +91,4 @@ email to client-dev+subscribe@letsencrypt.org)
 
 .. _Freenode: https://freenode.net
 .. _client-dev: https://groups.google.com/a/letsencrypt.org/forum/#!forum/client-dev
+.. _CONTRIBUTING.rst: https://github.com/letsencrypt/lets-encrypt-preview/blob/master/CONTRIBUTING.rst