diff --git a/docs/src/reference/asciidoc/appendix-reactormigration-communicating.adoc b/docs/src/reference/asciidoc/appendix-reactormigration-communicating.adoc
new file mode 100644
index 00000000..90731e4f
--- /dev/null
+++ b/docs/src/reference/asciidoc/appendix-reactormigration-communicating.adoc
@@ -0,0 +1,40 @@
+=== Communicating with a Machine
+We've added new reactive methods to `StateMachine` while still keeping old blocking event
+methods in place.
+
+====
+[source,java,indent=0]
+----
+include::samples/DocsMigrationTests.java[tags=snippetA]
+----
+====
+
+We're now solely working on a spring `Message` and reactor `Mono` and `Flux` classes.
+You can send a `Mono` of a `Message` and receive back a `Flux` of `StateMachineEventResult`.
+Remember that nothing happens until you subscribe to this `Flux`.
+
+====
+[source,java,indent=0]
+----
+include::samples/DocsMigrationTests.java[tags=snippetB1]
+----
+====
+
+You can also send a `Flux` of messages instead of a single `Mono` message.
+
+====
+[source,java,indent=0]
+----
+include::samples/DocsMigrationTests.java[tags=snippetB2]
+----
+====
+
+All of the reactor methods are on your disposal and for example not to block and
+do something when event handling is completed, you could do something like.
+
+====
+[source,java,indent=0]
+----
+include::samples/DocsMigrationTests.java[tags=snippetB3]
+----
+====
diff --git a/docs/src/reference/asciidoc/appendix-reactormigration.adoc b/docs/src/reference/asciidoc/appendix-reactormigration.adoc
index 249fb9b6..013941b9 100644
--- a/docs/src/reference/asciidoc/appendix-reactormigration.adoc
+++ b/docs/src/reference/asciidoc/appendix-reactormigration.adoc
@@ -1,9 +1,10 @@
 [appendix]
 [[appendix-reactormigrationguide]]
 == Reactor Migration Guide
-
 Main task for a work for `3.x` has been to both internally and externally to move and change
 as much as we can from imperative code into a reactive world. This means that some
 of a main interfaces has added a new reative methods and most of a internal execution locig
 has been moved over to handled by a reactor. Essentially what this means is that thread handling
 is considerably different compared to `2.x`. Following chapters go throught all these changes.
+
+include::appendix-reactormigration-communicating.adoc[]
diff --git a/spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/DocsMigrationTests.java b/spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/DocsMigrationTests.java
new file mode 100644
index 00000000..460517f3
--- /dev/null
+++ b/spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/DocsMigrationTests.java
@@ -0,0 +1,58 @@
+/*
+ * Copyright 2019 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.statemachine.docs;
+
+import org.springframework.messaging.Message;
+import org.springframework.messaging.support.MessageBuilder;
+import org.springframework.statemachine.StateMachine;
+import org.springframework.statemachine.StateMachineEventResult;
+
+import reactor.core.publisher.Flux;
+import reactor.core.publisher.Mono;
+
+public class DocsMigrationTests {
+
+	StateMachine<String, String> machine;
+
+	interface StateMachineDocs<S, E> extends StateMachine<S, E> {
+		// tag::snippetA[]
+		Flux<StateMachineEventResult<S, E>> sendEvent(Mono<Message<E>> event);
+
+		Flux<StateMachineEventResult<S, E>> sendEvents(Flux<Message<E>> events);
+		// end::snippetA[]
+	}
+
+	public void sample1() {
+		// tag::snippetB1[]
+		Message<String> message = MessageBuilder.withPayload("EVENT").build();
+		machine.sendEvent(Mono.just(message)).subscribe();
+		// end::snippetB1[]
+		// tag::snippetB2[]
+		machine.sendEvents(Flux.just(message)).subscribe();
+		// end::snippetB2[]
+	}
+
+	public void sample2() {
+		// tag::snippetB3[]
+		Mono<Message<String>> mono = Mono.just(MessageBuilder.withPayload("EVENT").build());
+		machine.sendEvent(mono)
+			.doOnComplete(() -> {
+				System.out.println("Event handling complete");
+			})
+			.subscribe();
+		// end::snippetB3[]
+	}
+}