Re-organize README, split off contribution guide

CONTRIBUTING.md

+## Contributing to uw-spring-security
+
+This project follows a collaboration workflow similar to what is described in the "Integration Manager" section of http://git-scm.com/book/en/Distributed-Git-Distributed-Workflows. 
+The primary repository for this project is https://git.doit.wisc.edu/adi-ia/uw-spring-security/. Few developers will have 'push' access to this repository; the preferred permission will be 'fetch' only.
+
+**No credentials for any remote systems are allowed in this project.** The only credentials found within this repository are those needed to communicate with the services on the local development environment.
+
+Each developer should:
+
+1. Fork the primary repository into their personal namespace.
+2. Clone the fork to their workstation.
+3. Create branches for each unit of work.
+4. When done, push the branch up to their personal fork.
+5. Submit a pull request from the branch in their personal fork to the primary repository.
+
+This process allows us to make use of gitlab's code review tools and gives us the flexibility to pick and choose which features are ready for promotion at different times.
+

README.md

 ## uw-spring-security
 
-This project is intended to provide a re-usable library that integrates Spring Security with UW's common
+This project is intended to provide a re-usable library that integrates [Spring Security](http://projects.spring.io/spring-security/) with UW's common
 authentication approach. 
 
 The core of the project contains a re-usable extension of Spring's [UserDetails](http://docs.spring.io/spring-security/site/docs/3.2.6.RELEASE/apidocs/org/springframework/security/core/userdetails/UserDetails.html) called *UWUserDetails*. This interface (and implementations) provide
 commonly used user attributes, like PVI, UDDS membership, full name, and email address.
 
-### Include in your project
+### Why this?
+
+[Spring Security](http://projects.spring.io/spring-security/) is an incredibly powerful and amazing way to secure your web application. There is arguably no better tool for Spring applications.
+
+[Spring Security](http://projects.spring.io/spring-security/) however is terribly complex to integrate in a project. [Read through the 'Hello World' example in Spring Security's reference docs](http://docs.spring.io/spring-security/site/docs/4.0.3.RELEASE/reference/htmlsingle/#jc).
+It's a long read, and when you are done *you will be no closer to having Spring Security configured in a manner that's appropriate for use in a UW application*.
+
+Enter uw-spring-security. To get Spring Security fully integrated in your project, for both local development **and** deployed instances behind a Shibboleth Service Provider:
+
+```java
+@Configuration
+@Import(EverythingRequiresAuthenticationConfiguration.class)
+public class MyApplicationConfiguration {
+}
+```
+
+That's it! Your application will now be able to call Spring Security's:
+
+```java
+SecurityContextHolder.getContext().getAuthentication().getPrincipal()
+```
+
+and get back an instance of [UWUserDetails](uw-spring-security-core/src/main/java/edu/wisc/uwss/UWUserDetails.java), which looks like this:
+
+```
+{
+  pvi: "UW000A000",
+  username: "admin",
+  password: null,
+  fullName: "Amy Administrator",
+  emailAddress: "amy.administrator@demo.wisc.edu",
+  uddsMembership: [
+    "A535900"
+  ],
+  authorities: [ ],
+  accountNonExpired: true,
+  accountNonLocked: true,
+  credentialsNonExpired: true,
+  enabled: true,
+  eppn: null,
+  emailAddressHash: "b09ed4fa2272feede8b472d1184829dd",
+  source: "local-users",
+  customLogoutUrl: null,
+  isisEmplid: null,
+  firstName: null,
+  lastName: null
+}
+```
+
+This project was recently the focus of an [Application Design Review Brown Bag](https://wiki.doit.wisc.edu/confluence/display/SOACOE/2016-03-04+Agenda), you can also find more detailed 
+usage documentation on the [project wiki](https://git.doit.wisc.edu/adi-ia/uw-spring-security/wiki).
+
+### Adding the dependencies to your project
 
 The following instructions assuming that you have access to the UW Releases repository in our [Maven Repository Manager](https://wiki.doit.wisc.edu/confluence/display/ST/Maven+Repository+Manager).
 
-Add the following to your Maven pom.xml:
-
-    <dependency>
-      <groupId>edu.wisc.uwss</groupId>
-      <artifactId>uw-spring-security-core</artifactId>
-      <version>0.4.7</version>
-    </dependency>
-    <dependency>
-      <groupId>edu.wisc.uwss</groupId>
-      <artifactId>uw-spring-security-config</artifactId>
-      <version>0.4.7</version>
-    </dependency>
+```xml
+  <repositories>
+    <repository>
+      <id>code.doit-uw-releases</id>
+      <url>https://code.doit.wisc.edu/maven/content/repositories/uw-releases/</url>
+    </repository>
+  </repositories>
+```
+
+Add the following dependencies:
+
+```xml
+  <dependency>
+    <groupId>edu.wisc.uwss</groupId>
+    <artifactId>uw-spring-security-core</artifactId>
+  </dependency>
+  <dependency>
+    <groupId>edu.wisc.uwss</groupId>
+    <artifactId>uw-spring-security-config</artifactId>
+  </dependency>
+```
     
 The former, -core, should be a dependency in modules that integrate the user model within your service tier. The latter, -config, depends on -core and should be a dependency of your web application.  
     
-The uw-spring-security-sample-war is an example of how to activate the Spring `@Configuration` classes provided by the -config module in your application. Look at the *edu.wisc.uwss.sample.configuration* package for more detail. A convenient starting point is to `@Import` *edu.wisc.uwss.configuration.EverythingRequiresAuthenticationConfiguration*, see the javadocs on that class for more detail.
+The uw-spring-security-sample-war is an example of how to activate the Spring `@Configuration` classes provided by the -config module in your application. Look at the *edu.wisc.uwss.sample.configuration* package for more detail. 
 
-## Contributing
-
-This project is built on contributions from application developers in DoIT's community. Since we all regularly need to integrate with UW's
-user data model and authentication mechanisms, 
-
-### Developer requirements
-
-* Java 8+
-* Maven 3.2+
-
-### Contributing
-
-This project follows a collaboration workflow similar to what is described in the "Integration Manager" section of http://git-scm.com/book/en/Distributed-Git-Distributed-Workflows.
-It can also be described using the term "Fork and Pull."
-
-The primary repository for this project is https://git.doit.wisc.edu/adi-ia/uw-spring-security. Few developers will have 'push' access to this repository; the preferred permission will be 'fetch' only.
-
-Each developer should:
-
-1. Fork the primary repository into their personal namespace.
-2. Clone the fork to their workstation.
-3. Create branches for each unit of work.
-4. When done, push the branch up to their personal fork.
-5. Submit a pull request from the branch in their personal fork to the primary repository.
+### Release Management
 
-This process allows us to make use of gitlab's code review tools and gives us the flexibility to pick and choose
-which features are ready for promotion at different times.
+This project follows [Semantic Versioning](http://semver.org). Releases are published to the 'UW Releases' Repository in the [Shared Tools Maven Artifact Repository](https://wiki.doit.wisc.edu/confluence/display/ST/Maven+Repository+Manager)
 
-### Release Management
+Add the following repository to your Maven/Gradle build file:
 
-This project follows [Semantic Versioning](http://semver.org). Releases will be published with the Maven release plugin.
\ No newline at end of file
+```xml
+  <repositories>
+    <repository>
+      <id>code.doit-uw-releases</id>
+      <url>https://code.doit.wisc.edu/maven/content/repositories/uw-releases/</url>
+    </repository>
+  </repositories>
+```
\ No newline at end of file