Improvements to documentation.

See gh-12.

docs/index.html

@@ -38,9 +38,12 @@ badges:
 
 {% capture billboard_description %}
 
-Spring Vault provides familiar Spring abstractions and Client support for Spring applications. It offers both low-level and
+Spring Vault provides familiar Spring abstractions and client-side support for accessing, storing and revoking secrets. It offers both low-level and
 high-level abstractions for interacting with Vault, freeing the user from infrastructural concerns.
 
+With https://www.vaultproject.io[Hashicorp's Vault] you have a central place to manage external secret data for applications across all environments.
+Vault can manage static and dynamic secrets such as application data, username/password for remote applications/resources and provide credentials for external services such as MySQL, PostgreSQL, Apache Cassandra, Consul, AWS and more.
+
 {% endcapture %}
 
 {% capture main_content %}

src/main/asciidoc/preface.adoc

@@ -21,7 +21,7 @@ To learn more about Spring, you can refer to the comprehensive (and sometimes di
 
 Security and working with secrets is a concern of every developer working with databases, user credentials or API keys. Vault steps in by providing a secure storage combined with access control, revocation, key rolling and auditing. In short: Vault is a service for securely accessing and storing  secrets. A secret is anything that you want to tightly control access to, such as API keys, passwords, certificates, and more.
 
-The jumping off ground for learning about Vault is www.vaultproject.io. Here is a list of useful resources:
+The jumping off ground for learning about Vault is https://www.vaultproject.io[www.vaultproject.io]. Here is a list of useful resources:
 
 * The manual introduces Vault and contains links to getting started guides, reference documentation and tutorials.
 
@@ -34,7 +34,7 @@ The jumping off ground for learning about Vault is www.vaultproject.io. Here is
 [[requirements]]
 == Requirements
 
-Spring Vault 1.x binaries requires JDK level 6.0 and above, and http://spring.io/docs[Spring Framework] {springVersion} and above.
+Spring Vault 1.x binaries requires JDK level 6.0 and above, and http://spring.io/docs[Spring Framework] {springVersion} and above. While we maintain Java 6 compatibility, new projects should consider using Java 8  .
 
 In terms of Vault, https://www.vaultproject.io/[Vault] at least 0.5.
 
@@ -50,7 +50,7 @@ There are a few support options available:
 [[get-started:help:community]]
 ==== Community Forum
 
-Spring Vault on Stackoverflow http://stackoverflow.com/questions/tagged/spring-vault[Stackoverflow] is a tag for all Spring Vault users to share information and help each other. Note that registration is needed *only* for posting.
+Post questions questions regarding Spring Vault on http://stackoverflow.com/questions/tagged/spring-vault[Stackoverflow] to share information and help each other. Note that registration is needed *only* for posting.
 
 [[get-started:help:professional]]
 ==== Professional Support
@@ -60,4 +60,4 @@ Professional, from-the-source support, with guaranteed response time, is availab
 [[get-started:up-to-date]]
 === Following Development
 
-For information on the Spring Vault source code repository, nightly builds and snapshot artifacts please see the http://projects.spring.io/spring-vault/[Spring Vault homepage]. You can help make Spring Vault best serve the needs of the Spring community by interacting with developers through the Community on http://stackoverflow.com/questions/tagged/spring-vault[Stackoverflow]. If you encounter a bug or want to suggest an improvement, please create a ticket on the Spring Vault issue https://github.com/spring-projects/spring-vault/issues[tracker]. To stay up to date with the latest news and announcements in the Spring ecosystem, subscribe to the Spring Community http://spring.io[Portal]. Lastly, you can follow the Spring http://spring.io/blog[blog ]or the project team on Twitter (http://twitter.com/springcentral[SpringCentral]).
+For information on the Spring Vault source code repository, nightly builds and snapshot artifacts please see the http://projects.spring.io/spring-vault/[Spring Vault homepage]. You can help make Spring Vault best serve the needs of the Spring community by interacting with developers through the Community on http://stackoverflow.com/questions/tagged/spring-vault[Stackoverflow]. If you encounter a bug or want to suggest an improvement, please create a ticket on the Spring Vault issue https://github.com/spring-projects/spring-vault/issues[tracker]. To stay up to date with the latest news and announcements in the Spring ecosystem, subscribe to the Spring Community http://spring.io[Portal]. Lastly, you can follow the Spring http://spring.io/blog[blog ]or the project team on Twitter (http://twitter.com/springcentral[SpringCentral]).

src/main/asciidoc/reference/getting-started.adoc

@@ -45,12 +45,25 @@ You will also need to add the location of the Spring Milestone repository for ma
 
 The repository is also http://repo.spring.io/milestone/org/springframework/vault/[browseable here].
 
-You may also want to set the logging level to `DEBUG` to see some additional information, edit the log4j.properties file to have
+You may also want to set the logging level to `DEBUG` to see some additional information, edit the `logback.xml` file to have
 
 [source]
 ----
-log4j.category.org.springframework.vault=DEBUG
-log4j.appender.stdout.layout.ConversionPattern=%d{ABSOLUTE} %5p %40.40c:%4L - %m%n
+<configuration>
+
+    <appender name="console" class="ch.qos.logback.core.ConsoleAppender">
+        <encoder>
+            <pattern>%d %5p %40.40c:%4L - %m%n</pattern>
+        </encoder>
+    </appender>
+
+    <logger name="org.springframework.vault" level="debug" />
+
+    <root level="info">
+        <appender-ref ref="console" />
+    </root>
+
+</configuration>
 ----
 Create a simple `Secrets` class to persist:
 
@@ -115,17 +128,19 @@ Even in this simple example, there are few things to take notice of
 
 * You can instantiate the central helper class of Spring Vault,
 <<vault-template,`VaultTemplate`>>, using the `org.springframework.vault.client.VaultClient`
- object and the `ClientAuthentication`.
+object and the `ClientAuthentication`.
+* Vault is expected to be configured with a root token of
+`00000000-0000-0000-0000-000000000000` to run this application.
 * The mapper works against standard POJO objects without the need for any
 additional metadata (though you can optionally provide that information).
 * Mapping conventions can use field access. Notice the `Secrets` class has only getters.
 * If the constructor argument names match the field names of the stored document,
-they will be used to instantiate the object
+they will be used to instantiate the object.
 
 [[vault.core.connection]]
 == Connecting to Vault with Spring
 
-One of the first tasks when using Vault and Spring is to create a `org.springframework.vault.client.VaultClient` object using the IoC container.
+One of the first tasks when using Vault and Spring is to create a `org.springframework.vault.client.VaultClient` object using the IoC container. This is useful to use `VaultOperations` from different places inside of your code. Using Spring Vault with bean management ensures a consistent session management where the session is disposed as your application terminates.
 
 [[vault.core.vault-java-config]]
 === Registering a Vault instance using Java based metadata
@@ -358,4 +373,4 @@ return vaultTemplate.doWithVault(new ClientCallback<VaultInitializationResponse>
         }
     });
 ----
-====
+====