Merge branch 'documentation-improvements' into 'master'

Re-organize README, split off contribution guide

This pull request is a starting point for improving the documentation prior to the upcoming brownbag.

Starting with the README and contribution guide, I'll be poring over the existing docs trying to come up with examples. I'm thinking the wiki here in git.doit will be helpful as well.

See merge request !4

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/wikis/home).
+
+### 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