DATAMONGO-1032 - Polished Asciidoctor documentation.

Author: odrotbohm

src/main/asciidoc/index.adoc

@@ -1,27 +1,27 @@
 = Spring Data MongoDB - Reference Documentation
-Mark Pollack, Thomas Risberg, Oliver Gierke, Costin Leau, Jon Brisbin, Thomas Darimont, Christoph Strobl
+Mark Pollack; Thomas Risberg; Oliver Gierke; Costin Leau; Jon Brisbin; Thomas Darimont; Christoph Strobl
+:revnumber: {version}
+:revdate: {localdate}
 :toc:
+:toc-placement!:
 :spring-data-commons-docs: https://raw.githubusercontent.com/spring-projects/spring-data-commons/master/src/main/asciidoc
 
-{version}
-
-© 2008-2014 The original authors.
+(C) 2008-2014 The original authors.
 
 NOTE: _Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically._
 
+toc::[]
+
 include::preface.adoc[]
-include::introduction/introduction.adoc[]
 
-:leveloffset: 1
-include::introduction/requirements.adoc[]
-include::introduction/getting-started.adoc[]
+:leveloffset: +1
 include::{spring-data-commons-docs}/repositories.adoc[]
+:leveloffset: -1
 
-:leveloffset: 0
 [[reference]]
 = Reference Documentation
 
-:leveloffset: 1
+:leveloffset: +1
 include::reference/introduction.adoc[]
 include::reference/mongodb.adoc[]
 include::reference/mongo-repositories.adoc[]
@@ -30,12 +30,14 @@ include::reference/mapping.adoc[]
 include::reference/cross-store.adoc[]
 include::reference/logging.adoc[]
 include::reference/jmx.adoc[]
+:leveloffset: -1
 
-:leveloffset: 0
+[[appendix]]
 = Appendix
 
 :numbered!:
-:leveloffset: 1
-include::{spring-data-commons-docs}/repository-namespace-reference.adoc[]
+:leveloffset: +1
 include::{spring-data-commons-docs}/repository-namespace-reference.adoc[]
+include::{spring-data-commons-docs}/repository-populator-namespace-reference.adoc[]
 include::{spring-data-commons-docs}/repository-query-keywords-reference.adoc[]
+:leveloffset: -1

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

@@ -1,5 +1,59 @@
 [[preface]]
-[preface]
 = Preface
 
 The Spring Data MongoDB project applies core Spring concepts to the development of solutions using the MongoDB document style data store.  We provide a "template" as a high-level abstraction for storing and querying documents. You will notice similarities to the JDBC support in the Spring Framework.
+
+This document is the reference guide for Spring Data - Document Support. It explains Document module concepts and semantics and the syntax for various stores namespaces.
+
+This section provides some basic introduction to Spring and Document database. The rest of the document refers only to Spring Data Document features and assumes the user is familiar with document databases such as MongoDB and CouchDB as well as Spring concepts.
+
+[[get-started:first-steps:spring]]
+== Knowing Spring
+Spring Data uses Spring framework's http://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/spring-core.html[core] functionality, such as the http://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/beans.html[IoC] container, http://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/validation.html#core-convert[type conversion system], http://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/expressions.html[expression language], http://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/jmx.html[JMX integration], and portable http://docs.spring.io/spring/docs/3.2.x/spring-framework-reference/html/dao.html#dao-exceptions[DAO exception hierarchy]. While it is not important to know the Spring APIs, understanding the concepts behind them is. At a minimum, the idea behind IoC should be familiar for whatever IoC container you choose to use.
+
+The core functionality of the MongoDB and CouchDB support can be used directly, with no need to invoke the IoC services of the Spring Container. This is much like `JdbcTemplate` which can be used 'standalone' without any other services of the Spring container. To leverage all the features of Spring Data document, such as the repository support, you will need to configure some parts of the library using Spring.
+
+To learn more about Spring, you can refer to the comprehensive (and sometimes disarming) documentation that explains in detail the Spring Framework. There are a lot of articles, blog entries and books on the matter - take a look at the Spring framework http://spring.io/docs[home page ] for more information.
+
+[[get-started:first-steps:nosql]]
+== Knowing NoSQL and Document databases
+NoSQL stores have taken the storage world by storm. It is a vast domain with a plethora of solutions, terms and patterns (to make things worth even the term itself has multiple http://www.google.com/search?q=nosoql+acronym[meanings]). While some of the principles are common, it is crucial that the user is familiar to some degree with the stores supported by DATADOC. The best way to get acquainted to this solutions is to read their documentation and follow their examples - it usually doesn't take more then 5-10 minutes to go through them and if you are coming from an RDMBS-only background many times these exercises can be an eye opener.
+
+The jumping off ground for learning about MongoDB is http://www.mongodb.org/[www.mongodb.org]. Here is a list of other useful resources:
+
+* The http://docs.mongodb.org/manual/[manual] introduces MongoDB and contains links to getting started guides, reference documentation and tutorials.
+* The http://try.mongodb.org/[online shell] provides a convenient way to interact with a MongoDB instance in combination with the online http://docs.mongodb.org/manual/tutorial/getting-started/[tutorial.]
+* MongoDB http://docs.mongodb.org/ecosystem/drivers/java/[Java Language Center]
+* Several http://www.mongodb.org/books[books] available for purchase
+* Karl Seguin's online book: http://openmymind.net/mongodb.pdf[The Little MongoDB Book]
+
+[[requirements]]
+== Requirements
+
+Spring Data MongoDB 1.x binaries requires JDK level 6.0 and above, and http://spring.io/docs[Spring Framework] 3.2.x and above.
+
+In terms of document stores, http://www.mongodb.org/[MongoDB] preferably version 2.4.
+
+== Additional Help Resources
+
+Learning a new framework is not always straight forward. In this section, we try to provide what we think is an easy to follow guide for starting with Spring Data Document module. However, if you encounter issues or you are just looking for an advice, feel free to use one of the links below:
+
+[[get-started:help]]
+=== Support
+
+There are a few support options available:
+
+[[get-started:help:community]]
+==== Community Forum
+
+Spring Data on Stackoverflow http://stackoverflow.com/questions/tagged/spring-data[Stackoverflow ] is a tag for all Spring Data (not just Document) users to share information and help each other. Note that registration is needed *only* for posting.
+
+[[get-started:help:professional]]
+==== Professional Support
+
+Professional, from-the-source support, with guaranteed response time, is available from http://gopivotal.com/[Pivotal Sofware, Inc.], the company behind Spring Data and Spring.
+
+[[get-started:up-to-date]]
+=== Following Development
+
+For information on the Spring Data Mongo source code repository, nightly builds and snapshot artifacts please see the http://projects.spring.io/spring-data-mongodb/[Spring Data Mongo homepage]. You can help make Spring Data best serve the needs of the Spring community by interacting with developers through the Community on http://stackoverflow.com/questions/tagged/spring-data[Stackoverflow]. To follow developer activity look for the mailing list information on the Spring Data Mongo homepage. If you encounter a bug or want to suggest an improvement, please create a ticket on the Spring Data issue https://jira.spring.io/browse/DATAMONGO[tracker]. To stay up to date with the latest news and announcements in the Spring eco system, subscribe to the Spring Community http://spring.io[Portal]. Lastly, you can follow the SpringSource Data http://spring.io/blog[blog ]or the project team on Twitter (http://twitter.com/SpringData[SpringData]).

src/main/asciidoc/introduction/introduction.adoc

@@ -8,3 +8,4 @@ This part of the reference documentation explains the core functionality offered
 <<mongo.core>> introduces the MongoDB module feature set.
 
 <<mongo.repositories>> introduces the repository support for MongoDB.
+