diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000000000000000000000000000000000000..2aaf393afac3c350e48b2ad6b1f832f202048e12
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,17 @@
+## 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.
+
diff --git a/README.md b/README.md
index f5fa0d820ab736dbb730e81eb7377ec23039a78f..369cca6744b1875904b0f6934201c017f1f0dcfd 100644
--- a/README.md
+++ b/README.md
@@ -1,60 +1,104 @@
## 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