Some Docs improvements

src/reference/asciidoc/core.adoc

@@ -4,7 +4,7 @@
 [[spring-integration-core-msg]]
 This section covers all aspects of the core messaging API in Spring Integration.
 It covers messages, message channels, and message endpoints.
-It also covers many of the enterprise integration patterns, such as filter, router, transformer, service activator , splitter, and aggregator.
+It also covers many of the enterprise integration patterns, such as filter, router, transformer, service activator, splitter, and aggregator.
 
 This section also contains material about system management, including the control bus and message history support.
 

src/reference/asciidoc/index-header.adoc

@@ -2,16 +2,6 @@
 = Spring Integration Reference Guide
 Mark Fisher; Marius Bogoevici; Iwein Fuld; Jonas Partner; Oleg Zhurakousky; Gary Russell; Dave Syer; Josh Long; David Turanski; Gunnar Hillert; Artem Bilan; Amol Nayak; Jay Bryant
 
-ifdef::backend-html5[]
-*{revnumber}*
-
-NOTE: This documentation is also available as https://docs.spring.io/spring-integration/docs/current/reference/html/index.html[multiple (faster to load) HTML pages] and as https://docs.spring.io/spring-integration/docs/current/reference/pdf/spring-integration-reference.pdf[PDF].
-endif::[]
-
-ifdef::backend-pdf[]
-NOTE: This documentation is also available as https://docs.spring.io/spring-integration/docs/current/reference/html/index.html[multiple (faster to load) HTML pages] and as a single https://docs.spring.io/spring-integration/docs/current/reference/html/index-single.html[(more easily searchable) HTML file].
-endif::[]
-
 (C) 2009 - 2022 VMware, Inc.
 All rights reserved.
 

src/reference/asciidoc/index-single.adoc

@@ -5,6 +5,16 @@
 // BE SURE TO PRECEDE ALL include:: with a blank line - see https://github.com/asciidoctor/asciidoctor/issues/1297
 include::./index-header.adoc[]
 
+ifdef::backend-html5[]
+*{revnumber}*
+
+NOTE: This documentation is also available as https://docs.spring.io/spring-integration/docs/current/reference/html/index.html[multiple (faster to load) HTML pages] and as https://docs.spring.io/spring-integration/docs/current/reference/pdf/spring-integration-reference.pdf[PDF].
+endif::[]
+
+ifdef::backend-pdf[]
+NOTE: This documentation is also available as https://docs.spring.io/spring-integration/docs/current/reference/html/index.html[multiple (faster to load) HTML pages] and as a single https://docs.spring.io/spring-integration/docs/current/reference/html/index-single.html[(more easily searchable) HTML file].
+endif::[]
+
 include::./preface.adoc[]
 
 include::./whats-new.adoc[]

src/reference/asciidoc/index.adoc

@@ -2,73 +2,82 @@
 
 include::./index-header.adoc[]
 
+ifdef::backend-html5[]
+*{revnumber}*
+
+NOTE: This documentation is also available as single searchable link:index-single.html[html] and link:../pdf/spring-integration-reference.pdf[pdf] documents.
+endif::[]
+
+ifdef::backend-pdf[]
+NOTE: This documentation is also available as https://docs.spring.io/spring-integration/docs/current/reference/html/index.html[multiple (faster to load) HTML pages] and as a single https://docs.spring.io/spring-integration/docs/current/reference/html/index-single.html[(more easily searchable) HTML file].
+endif::[]
+
 Welcome to the Spring Integration reference documentation!
-This documentation is also available as single searchable link:index-single.html[html] and link:../pdf/spring-integration-reference.pdf[pdf] documents.
 
 [horizontal]
-<<./preface.adoc#preface,Preface>> ::
-<<./whats-new.adoc#whats-new,What's New>> ::
-<<./overview.adoc#spring-integration-introduction,Overview>> ::
-<<./core.adoc#spring-integration-core-messaging,Core Messaging>> ::
-<<./message.adoc#message,Message>> ::
-<<./message-routing.adoc#messaging-routing-chapter,Message Routing>> ::
-<<./message-transformation.adoc#messaging-transformation-chapter,Message Transformation>> ::
-<<./messaging-endpoints.adoc#messaging-endpoints-chapter,Messaging Endpoints>> ::
-<<./dsl.adoc#java-dsl,Java DSL>> ::
-<<./kotlin-dsl.adoc#kotlin-dsl,Kotlin DSL>> ::
-<<./system-management.adoc#system-management-chapter,System Management>> ::
-<<./reactive-streams.adoc#reactive-streams,Reactive Streams Support>> ::
+<<./preface.adoc#preface,Preface>> :: General project info, conventions
+<<./whats-new.adoc#whats-new,What's New>> :: Features and changes made in the current version
+<<./overview.adoc#spring-integration-introduction,Overview>> :: Introduction to EIP and its implementation in the project
+<<./core.adoc#spring-integration-core-messaging,Core Messaging>> :: Main project abstractions and components
+<<./message.adoc#message,Message>> :: Details about the message abstraction implementations
+<<./message-routing.adoc#messaging-routing-chapter,Message Routing>> :: main EIP components: router, splitter, aggregator, filter etc.
+<<./message-transformation.adoc#messaging-transformation-chapter,Message Transformation>> :: Transformer, content enricher, claim check, codec
+<<./messaging-endpoints.adoc#messaging-endpoints-chapter,Messaging Endpoints>> :: Consumer endpoints, service activator, gateway, scripting, AOP aspects etc.
+<<./dsl.adoc#java-dsl,Java DSL>> :: Details about Java DSL for EIP
+<<./kotlin-dsl.adoc#kotlin-dsl,Kotlin DSL>> :: Details about Kotlin DSL for EIP
+<<./system-management.adoc#system-management-chapter,System Management>> :: Message store, control bus, integration graph, metrics, JMX
+<<./reactive-streams.adoc#reactive-streams,Reactive Streams Support>> :: Details about Reactive Streams support: message channels, channel adapters etc.
 
 [horizontal]
 **Integration Endpoints** ::
 
 [horizontal]
-<<./endpoint-summary.adoc#spring-integration-endpoints,Integration Endpoint Summary>> ::
-<<./amqp.adoc#amqp,AMQP Support>> ::
-<<./event.adoc#applicationevent,Spring `ApplicationEvent` Support>> ::
-<<./feed.adoc#feed,Feed Adapter>> ::
-<<./file.adoc#files,File Support>> ::
-<<./ftp.adoc#ftp,FTP/FTPS Adapters>> ::
-<<./gemfire.adoc#gemfire,Pivotal GemFire and Apache Geode Support>> ::
-<<./graphql.adoc#graphql,GraphQL Support>> ::
-<<./http.adoc#http,HTTP Support>> ::
-<<./jdbc.adoc#jdbc,JDBC Support>> ::
-<<./jpa.adoc#jpa,JPA Support>> ::
-<<./jms.adoc#jms,JMS Support>> ::
-<<./jmx.adoc#jmx,JMX Support>> ::
-<<./kafka.adoc#kafka,Apache Kafka Support>> ::
-<<./mail.adoc#mail,Mail Support>> ::
-<<./mongodb.adoc#mongodb,MongoDb Support>> ::
-<<./mqtt.adoc#mqtt,MQTT Support>> ::
-<<./r2dbc.adoc#r2dbc,R2DBC Support>> ::
-<<./redis.adoc#redis,Redis Support>> ::
-<<./resource.adoc#resource,Resource Support>> ::
-<<./rsocket.adoc#rsocket,RSocket Support>> ::
-<<./sftp.adoc#sftp,SFTP Adapters>> ::
-<<./smb.adoc#smb,SMB Support>> ::
-<<./stomp.adoc#stomp,STOMP Support>> ::
-<<./stream.adoc#stream,Stream Support>> ::
-<<./syslog.adoc#syslog,Syslog Support>> ::
-<<./ip.adoc#ip,TCP and UDP Support>> ::
-<<./webflux.adoc#webflux,WebFlux Support>> ::
-<<./web-sockets.adoc#web-sockets,WebSockets Support>> ::
-<<./ws.adoc#ws,Web Services Support>> ::
-<<./xml.adoc#xml,XML Support - Dealing with XML Payloads>> ::
-<<./xmpp.adoc#xmpp,XMPP Support>> ::
-<<./zeromq.adoc#zeromq,ZeroMQ Support>> ::
-<<./zookeeper.adoc#zookeeper,Zookeeper Support>> ::
+<<./endpoint-summary.adoc#spring-integration-endpoints,Integration Endpoint Summary>> :: Protocol-specific channel adapters and gateways summary
+<<./amqp.adoc#amqp,AMQP Support>> :: AMQP channels, adapters and gateways
+<<./event.adoc#applicationevent,Spring `ApplicationEvent` Support>> :: Handling and consuming Spring application events with channel adapters
+<<./feed.adoc#feed,Feed Adapter>> :: RSS and Atom channel adapters
+<<./file.adoc#files,File Support>> :: Channel adapters and gateways for file system support
+<<./ftp.adoc#ftp,FTP/FTPS Adapters>> :: Channel adapters and gateways for FTP protocol
+<<./gemfire.adoc#gemfire,Apache Geode Support>> :: Apache Geode channel adapters, message store
+<<./graphql.adoc#graphql,GraphQL Support>> :: Channel adapters for GraphQL
+<<./http.adoc#http,HTTP Support>> :: Channel adapters and gateways for HTTP communication
+<<./jdbc.adoc#jdbc,JDBC Support>> :: Channel adapters and gateways for JDBC, message and metadata stores
+<<./jpa.adoc#jpa,JPA Support>> :: Channel adapters and gateways for JPA API
+<<./jms.adoc#jms,JMS Support>> :: Channel adapters and gateways for JMS API
+<<./jmx.adoc#jmx,JMX Support>> :: Channel adapters for JMX interaction, integration-specific MBean exporter
+<<./kafka.adoc#kafka,Apache Kafka Support>> :: Channels, adapters and gateways for Apache Kafka
+<<./mail.adoc#mail,Mail Support>> :: Channel adapters for Java Mail API
+<<./mongodb.adoc#mongodb,MongoDb Support>> :: Channels, adapters, gateways and message store for MongoDb
+<<./mqtt.adoc#mqtt,MQTT Support>> :: Channel adapters for MQTT protocol
+<<./r2dbc.adoc#r2dbc,R2DBC Support>> :: Channel adapters for R2DBC API
+<<./redis.adoc#redis,Redis Support>> ::  Channels, adapters, gateways and message store for Redis
+<<./resource.adoc#resource,Resource Support>> :: Spring resource channel adapters
+<<./rsocket.adoc#rsocket,RSocket Support>> :: Channel adapters for RSocket protocol
+<<./sftp.adoc#sftp,SFTP Adapters>> :: Channel adapters and gateways for FTP protocol
+<<./smb.adoc#smb,SMB Support>> :: Channel adapters and gateways for SMB protocol
+<<./stomp.adoc#stomp,STOMP Support>> :: Channel adapters and gateways for STOMP protocol
+<<./stream.adoc#stream,Stream Support>> :: Channel adapters for Java IO stream API
+<<./syslog.adoc#syslog,Syslog Support>> :: Channel adapters for Syslog protocol
+<<./ip.adoc#ip,TCP and UDP Support>> :: Channel adapters and gateways for TCP and UDP protocols
+<<./webflux.adoc#webflux,WebFlux Support>> :: Channel adapters and gateways for WebFlux API
+<<./web-sockets.adoc#web-sockets,WebSockets Support>> :: Channel adapters for WebSockets protocol
+<<./ws.adoc#ws,Web Services Support>> :: Channel adapters for SOAP protocol
+<<./xml.adoc#xml,XML Support - Dealing with XML Payloads>> :: Channel adapters and transformers for XML API, xPath
+<<./xmpp.adoc#xmpp,XMPP Support>> :: Channel adapters for XMPP protocol
+<<./zeromq.adoc#zeromq,ZeroMQ Support>> :: Channels and adapters for ZeroMQ protocol
+<<./zookeeper.adoc#zookeeper,Zookeeper Support>> :: Channel adapters for Zookeeper and Curator API
 
 [horizontal]
 **Appendices** ::
 
 [horizontal]
-<<./error-handling.adoc#error-handling,Error Handling>> ::
-<<./spel.adoc#spel,Spring Expression Language (SpEL)>> ::
-<<./message-publishing.adoc#message-publishing,Message Publishing>> ::
-<<./transactions.adoc#transactions,Transaction Support>> ::
-<<./security.adoc#security,Security in Spring Integration>> ::
-<<./configuration.adoc#configuration,Configuration>> ::
-<<./testing.adoc#testing,Testing support>> ::
-<<./samples.adoc#samples,Spring Integration Samples>> ::
-<<./resources.adoc#resources,Additional Resources>> ::
-<<./history.adoc#history,Change History>> ::
+<<./error-handling.adoc#error-handling,Error Handling>> :: Overview of error handling approaches in Spring Integration
+<<./spel.adoc#spel,Spring Expression Language (SpEL)>> :: Details about SpEL support
+<<./message-publishing.adoc#message-publishing,Message Publishing>> :: The Publisher annotation etc.
+<<./transactions.adoc#transactions,Transaction Support>> :: Overview of transactions support in Spring Integration
+<<./security.adoc#security,Security in Spring Integration>> :: Securing Spring Integration flows
+<<./configuration.adoc#configuration,Configuration>> :: Messaging annotations, task scheduler, global properties, message mapping
+<<./testing.adoc#testing,Testing support>> :: Test utilities, Integration mocks and testing framework
+<<./samples.adoc#samples,Spring Integration Samples>> :: The samples dedicated project
+<<./resources.adoc#resources,Additional Resources>> :: Other resources related to project
+<<./history.adoc#history,Change History>> :: The changes made in the project over time

src/reference/asciidoc/preface.adoc

@@ -68,3 +68,26 @@ Be aware, though, that SpringSource Tool Suite™ (STS) uses the same namespace
 == Conventions in This Guide
 
 In some cases, to aid formatting when specifying long fully qualified class names, we shorten `org.springframework` to `o.s` and `org.springframework.integration` to `o.s.i`, such as with `o.s.i.transaction.TransactionSynchronizationFactory`.
+
+[[overview-feedback]]
+== Feedback and Contributions
+
+For how-to questions or diagnosing or debugging issues, we suggest using Stack Overflow.
+Click https://stackoverflow.com/questions/tagged/spring-integration?tab=Newest[here] for a list of the latest questions.
+If you're fairly certain that there is a problem in the Spring Integration or would like to suggest a feature, please use the https://github.com/spring-projects/spring-integration/issues[GitHub Issues].
+
+If you have a solution in mind or a suggested fix, you can submit a pull request on https://github.com/spring-projects/spring-integration[GitHub].
+However, please keep in mind that, for all but the most trivial issues, we expect a ticket to be filed in the issue tracker, where discussions take place and leave a record for future reference.
+
+For more details see the guidelines at the https://github.com/spring-projects/spring-integration/blob/main/CONTRIBUTING.adoc[CONTRIBUTING], top-level project page.
+
+
+[[overview-getting-started]]
+== Getting Started
+
+If you are just getting started with Spring Integration, you may want to begin by creating a https://projects.spring.io/spring-boot/[Spring Boot]-based application.
+Spring Boot provides a quick (and opinionated) way to create a production-ready Spring-based application.
+It is based on the Spring Framework, favors convention over configuration, and is designed to get you up and running as quickly as possible.
+
+You can use https://start.spring.io/[start.spring.io] to generate a basic project (add `integration` as dependency) or follow one of the https://spring.io/guides["Getting Started" guides], such as https://spring.io/guides/gs/integration/[Getting Started Building an Integrating Data].
+As well as being easier to digest, these guides are very task focused, and most of them are based on Spring Boot.