CONTRIBUTING is markdwon again + polish README

The main way CONTRIBUTING will be viewed is on Github and the output
is just not good enough to justify using asciidoctor vs md/txt as
the recommended on the Github help page for contributing guidelines.

For example it was attractive to use a TOC and that works on Github
but doesn't look good. In the end it's a very short TOC and
maintaining manually is easy enough and it's easier to control the
look.

CONTRIBUTING.adoc → CONTRIBUTING.md

-[[contributing]]
-# Contributing  to the Spring Framework
+## Contributing  to the Spring Framework
 
 First off, thank you for taking the time to contribute!
 
-**Table of Contents**
+*Table of Contents*
 
-* <<conduct>>
-* <<how>>
-** <<how-question>>
-** <<how-ticket>>
-** <<how-pull-request>>
-* <<code-style>>
-* <<documentation>>
+* [Code of Conduct](#Code-of-Conduct)
+* [How to Contribute](#How-to-Contribute)
+  * [Discuss](#Discuss)
+  * [Create a Ticket](#Create-a-Ticket)
+  * [Submit a Pull Request](#Submit-a-Pull-Request)
+* [Source Code Style](#Source-Code-Style)
+* [Reference Docs](#Reference-Docs)
 
+### Code of Conduct
 
-
-[[conduct]]
-## Code of Conduct
-
-This project is governed by the link:CODE_OF_CONDUCT.adoc[Spring Code of Conduct].
+This project is governed by the [Spring Code of Conduct](CODE_OF_CONDUCT.adoc).
 By participating you are expected to uphold this code.
 Please report unacceptable behavior to spring-code-of-conduct@pivotal.io.
 
+### How to Contribute
 
-
-[[how]]
-## How to Contribute
-
-
-[[how-question]]
-### Discuss
+#### Discuss
 
 If you have a question, check StackOverflow using
-https://spring.io/questions[this list of tags], organized by Spring project.
+[this list of tags](https://spring.io/questions), organized by Spring project.
 Find an existing discussion or start a new one if necessary.
 
 If you suspect an issue, perform a search in the
-https://jira.spring.io/browse/SPR[JIRA issue tracker], using a few different keywords.
+[JIRA issue tracker](https://jira.spring.io/browse/SPR), using a few different keywords.
 When you find related issues and discussions, prior or current, it helps you to learn and
 it helps us to make a decision.
 
-
-
-[[how-ticket]]
-### Create a Ticket
+#### Create a Ticket
 
 Reporting an issue or making a feature request is a great way to contribute. Your feedback
 and the conversations that result from it provide a continuous flow of ideas. However,
-before you do that, please take the time to <<how-question,research first>>.
+before you do that, please take the time to [research first](#Discuss).
 
 When an issue is first created, it may not be assigned and will not have a fix version.
 Within a day or two, the issue is assigned to a specific committer and the target
@@ -59,24 +47,22 @@ When a fix is ready, the issue is marked "Resolved" and may still be re-opened.
 is released, the issue is permanently "Closed". If necessary, you will need to create a new,
 related ticket with a fresh description.
 
-
-
-[[how-pull-request]]
-### Submit a Pull Request
+#### Submit a Pull Request
 
 You can contribute a source code change by submitting a pull request.
 
 1. If you have not previously done so, please sign the
-https://cla.pivotal.io/sign/spring[Contributor License Agreement]. You will also be reminded
+[Contributor License Agreement](https://cla.pivotal.io/sign/spring). You will also be reminded
 automatically when you submit a pull request.
 
-1. For all but the most trivial of contributions, please <<how-ticket>>. The purpose of the
-ticket is to understand and discuss the underlying issue or feature. We use the JIRA issue tracker
-as the preferred place of record for conversations and conclusions. In that sense discussions
-directly under a PR are more implementation detail oriented and transient in nature.
+1. For all but the most trivial of contributions, please [create a ticket](#Create-a-Ticket).
+The purpose of the ticket is to understand and discuss the underlying issue or feature.
+We use the JIRA issue tracker as the preferred place of record for conversations and
+conclusions. In that sense discussions directly under a PR are more implementation detail
+oriented and transient in nature.
 
 1. Always check out the `master` branch and submit pull requests against it
-(for target version see link:settings.gradle[settings.gradle]).
+(for target version see [settings.gradle](settings.gradle)).
 Backports to prior versions will be considered on a case-by-case basis and reflected as
 the fix version in the issue tracker.
 
@@ -85,13 +71,13 @@ otherwise using succinct, lower-case, dash (-) delimited names, such as `fix-war
 
 1. Choose the granularity of your commits consciously and squash commits that represent
 multiple edits or corrections of the same logical change. See
-http://git-scm.com/book/en/Git-Tools-Rewriting-History[Rewriting History section of Pro Git]
+[Rewriting History section of Pro Git](http://git-scm.com/book/en/Git-Tools-Rewriting-History)
 for an overview of streamlining commit history.
 
 1. Format commit messages using 55 characters for the subject line, 72 lines for the
 description, followed by related issues, e.g. `Issues: SPR-1234, SPR-1235`.
 See the
-http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines[Commit Guidelines section of Pro Git]
+[Commit Guidelines section of Pro Git](http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines)
 for best practices around commit messages and use `git log` to see some examples.
 
 1. List the JIRA issue number in the PR description.
@@ -104,30 +90,24 @@ If asked to make corrections, simply push the changes against the same branch, a
 pull request will be updated. In other words, you do not need to create a new pull request
 when asked to make changes.
 
+### Source Code Style
 
+The wiki page
+[Spring Framework Code Style](https://github.com/spring-projects/spring-framework/wiki/Spring-Framework-Code-Style)
+defines the source file coding standards we use while the [IDEA formatting](https://github.com/spring-projects/spring-framework/wiki/Spring-Framework-IDEA-Code-Formatting)
+page describes the changes we make to the default code formatting settings in IntelliJ IDEA.
 
-[[code-style]]
-## Source Code Style
-
-* The https://github.com/spring-projects/spring-framework/wiki/Spring-Framework-Code-Style[Spring Framework Code Style]
-wiki page defines the the coding standards used for Spring Framework source files.
-* The https://github.com/spring-projects/spring-framework/wiki/Spring-Framework-IDEA-Code-Formatting[IDEA Code Formatting]
-wiki page describes changes we make to the default code formatting settings in Intellij IDEA.
-
-
-
-[[documentation]]
-## Reference Docs
+### Reference Docs
 
-The reference documentation is in the `src/docs/asciidoc` directory and, in
-http://asciidoctor.org/[Asciidoctor] format. For trivial changes, you may be able to browse,
+The reference documentation is in the [src/docs/asciidoc](src/docs/asciidoc) directory and, in
+[Asciidoctor](http://asciidoctor.org/) format. For trivial changes, you may be able to browse,
 edit source files, and submit directly from Github.
 
 When making changes locally, use `./gradlew asciidoctor` and then browse the result under
 `build/asciidoc/html5/index.html`.
 
 Asciidoctor also supports live editing. For more details read
-http://asciidoctor.org/docs/editing-asciidoc-with-live-preview/[Editing AsciiDoc with Live Preview].
+[Editing AsciiDoc with Live Preview](http://asciidoctor.org/docs/editing-asciidoc-with-live-preview/).
 Note that if you choose the
-http://asciidoctor.org/docs/editing-asciidoc-with-live-preview/#using-a-system-monitor[System Monitor]
+[System Monitor](http://asciidoctor.org/docs/editing-asciidoc-with-live-preview/#using-a-system-monitor)
 option, you can find a Guardfile under `src/docs/asciidoc`.

README.md

-Please read the
+This is the home of the Spring Framework that underlies all
+[Spring projects](https://spring.io/projects). Collectively the Spring Framework and the
+family of related Spring projects make up what we call "Spring".
+
+Spring provides everything you need beyond the Java language to create enterprise
+applications in a wide range of scenarios and architectures. Please read the
 [Overview](https://docs.spring.io/spring/docs/current/spring-framework-reference/overview.html#spring-introduction)
-in the reference documentation for a quick introduction.
+section in the reference for a more complete introduction.
+
+## Code of Conduct
 
 This project is governed by the [Spring Code of Conduct](CODE_OF_CONDUCT.adoc).
 By participating you are expected to uphold this code.
 Please report unacceptable behavior to spring-code-of-conduct@pivotal.io.
 
-For Maven repository information see [downloading Spring artifacts][], or if unable to
-use Maven or other transitive dependency management tools, see
-[building a distribution with dependencies][].
+## Artifacts
+
+For Maven repository information see
+[downloading Spring artifacts](https://github.com/spring-projects/spring-framework/wiki/Downloading-Spring-artifacts),
+or if unable to use Maven or other transitive dependency management tools, see
+[building a distribution with dependencies](https://github.com/spring-projects/spring-framework/wiki/Building-a-distribution-with-dependencies).
 
-Documentation is available in the form of [reference docs][], [Javadoc][], and Github Wiki pages.
+## Learn
 
-For contributing see the [contributor guidelines][] for details.
+The Spring Frameworks maintains
+[reference documentation](http://docs.spring.io/spring-framework/docs/current/spring-framework-reference/),
+Github [wiki pages](https://github.com/spring-projects/spring-framework/wiki), and an
+[API reference](http://docs.spring.io/spring-framework/docs/current/javadoc-api/).
 
-## Building from Source
-The Spring Framework uses a [Gradle][]-based build system. In the instructions
-below, [`./gradlew`][] is invoked from the root of the source tree and serves as
-a cross-platform, self-contained bootstrap mechanism for the build.
+You can find guides and tutorials on [https://spring.io](https://spring.io/guides).
 
-### Prerequisites
+## Build from Source
 
-[Git][] and [JDK 8 update 20 or later][JDK8 build]
+The Spring Framework uses a [Gradle](http://gradle.org) build. In the instructions below,
+the [Gradle Wrapper](http://vimeo.com/34436402) is invoked from the root of the source
+tree and serves as a cross-platform, self-contained bootstrap mechanism for the build.
 
+To build you will need [Git](http://help.github.com/set-up-git-redirect) and
+[JDK 8 update 20 or later](http://www.oracle.com/technetwork/java/javase/downloads).
 Be sure that your `JAVA_HOME` environment variable points to the `jdk1.8.0` folder
 extracted from the JDK download.
 
-### Check out sources
-`git clone git@github.com:spring-projects/spring-framework.git`
+Start by checking out the sources:
+```
+git clone git@github.com:spring-projects/spring-framework.git
+```
 
-### Import sources into your IDE
-Run `./import-into-eclipse.sh` or read `import-into-idea.md` as appropriate.
-> **Note:** Per the prerequisites above, ensure that you have JDK 8 configured properly in your IDE.
+To import into an IDE, ensure JDK 8 is configured. Then run `./import-into-eclipse.sh`
+or read [import-into-idea.md](import-into-idea.md). For IntelliJ please do read the
+instructions as a straight-up import will not work.
 
-### Install all spring-\* jars into your local Maven cache
-`./gradlew install`
+To compile, test, build all jars, distribution zips, and docs use:
+```
+./gradlew build
+```
 
-### Compile and test; build all jars, distribution zips, and docs
-`./gradlew build`
+To install all spring-\* jars into your local Maven cache:
+```
+./gradlew install
+```
 
-... and discover more commands with `./gradlew tasks`. See also the [Gradle
-build and release FAQ][].
+Discover more commands:
+```
+./gradlew tasks
+```
 
-## Staying in Touch
-Follow [@SpringCentral][] as well as [@SpringFramework][] and its [team members][]
-on Twitter. In-depth articles can be found at [The Spring Blog][], and releases
-are announced via our [news feed][].
+See also [CONTRIBUTING](CONTRIBUTING.md) and the
+[Gradle build and release FAQ](https://github.com/spring-projects/spring-framework/wiki/Gradle-build-and-release-FAQ).
+
+## Stay in Touch
+
+Follow [@SpringCentral](https://twitter.com/springcentral),
+[@SpringFramework](https://twitter.com/springframework), and its
+[team members](https://twitter.com/springframework/lists/team/members) on Twitter.
+In-depth articles can be found at [The Spring Blog](http://spring.io/blog/),
+and releases are announced via our [news feed](http://spring.io/blog/category/news).
 
 ## License
-The Spring Framework is released under version 2.0 of the [Apache License][].
-
-[downloading Spring artifacts]: https://github.com/spring-projects/spring-framework/wiki/Downloading-Spring-artifacts
-[building a distribution with dependencies]: https://github.com/spring-projects/spring-framework/wiki/Building-a-distribution-with-dependencies
-[Javadoc]: http://docs.spring.io/spring-framework/docs/current/javadoc-api/
-[reference docs]: http://docs.spring.io/spring-framework/docs/current/spring-framework-reference/
-[Spring Framework JIRA]: https://jira.spring.io/browse/SPR
-[Gradle]: http://gradle.org
-[`./gradlew`]: http://vimeo.com/34436402
-[Git]: http://help.github.com/set-up-git-redirect
-[JDK8 build]: http://www.oracle.com/technetwork/java/javase/downloads
-[Gradle build and release FAQ]: https://github.com/spring-projects/spring-framework/wiki/Gradle-build-and-release-FAQ
-[Pull requests]: https://help.github.com/categories/collaborating-on-projects-using-issues-and-pull-requests/
-[contributor guidelines]: https://github.com/spring-projects/spring-framework/blob/master/CONTRIBUTING.adoc
-[@SpringFramework]: https://twitter.com/springframework
-[@SpringCentral]: https://twitter.com/springcentral
-[team members]: https://twitter.com/springframework/lists/team/members
-[The Spring Blog]: http://spring.io/blog/
-[news feed]: http://spring.io/blog/category/news
-[Apache License]: http://www.apache.org/licenses/LICENSE-2.0
+
+The Spring Framework is released under version 2.0 of the
+[Apache License](http://www.apache.org/licenses/LICENSE-2.0).