Clarify that operator chaining order matters

ReactiveX/RxJava#3152

Author: DavidMGross

documentation/observable.markdown

@@ -17,7 +17,8 @@ id: observable
  operators</a> to link Observables together and change their behaviors.
 </p>
 <figure>
- <figcaption><p>This documentation accompanies its explanations with &ldquo;marble diagrams.&rdquo; Here is how marble diagrams represent Observables and transformations of Observables:</p></figcaption>
+ <figcaption><p>This documentation accompanies its explanations with &ldquo;marble diagrams.&rdquo; Here is how
+ marble diagrams represent Observables and transformations of Observables:</p></figcaption>
  <img src="{{ site.url }}/assets/operators/legend.png" style="width:100%;" />
 </figure>
 <h4>See Also</h4>
@@ -223,3 +224,19 @@ myObservable.subscribe(myOnNext, myError, myComplete);
  These pages include information about some operators that are not part of the core of ReactiveX but are
  implemented in one or more of language-specific implementations and/or optional modules.
 </p>
+<h2>Chaining Operators</h2>
+<p>
+ Most operators operate on an Observable and return an Observable. This allows you to apply these operators one
+ after the other, in a chain. Each operator in the chain modifies the Observable that results from the operation
+ of the previous operator.
+</p><p>
+ There are other patterns, like the Builder Pattern, in which a variety of methods of a particular class
+ operate on an item of that same class by modifying that object through the operation of the method. These
+ patterns also allow you to chain the methods in a similar way. But while in the Builder Pattern, the order in
+ which the methods appear in the chain does not usually matter, with the Observable operators <em>order
+ matters</em>.
+</p><p>
+ A chain of Observable operators do not operate independently on the original Observable that originates the
+ chain, but they operate <em>in turn</em>, each one operating on the Observable generated by the operator
+ immediately previous in the chain.
+</p>

documentation/operators.markdown

@@ -4,11 +4,30 @@ title: ReactiveX - Operators
 id: operators
 ---
 
+<h1>Introduction</h1>
+
 Each language-specific implementation of ReactiveX implements a set of operators. Although there is much overlap
 between implementations, there are also some operators that are only implemented in certain implementations.
 Also, each implementation tends to name its operators to resemble those of similar methods that are already
 familiar from other contexts in that language.
 
+<h2>Chaining Operators</h2>
+
+Most operators operate on an Observable and return an Observable. This allows you to apply these operators one
+after the other, in a chain. Each operator in the chain modifies the Observable that results from the operation
+of the previous operator.
+
+There are other patterns, like the Builder Pattern, in which a variety of methods of a particular class operate
+on an item of that same class by modifying that object through the operation of the method. These patterns also
+allow you to chain the methods in a similar way. But while in the Builder Pattern, the order in which the
+methods appear in the chain does not usually matter, with the Observable operators <em>order matters</em>.
+
+A chain of Observable operators do not operate independently on the original Observable that originates the
+chain, but they operate <em>in turn</em>, each one operating on the Observable generated by the operator
+immediately previous in the chain.
+
+<h2>The Operators of ReactiveX</h2>
+
 This page first lists what could be considered the &ldquo;core&rdquo; operators in ReactiveX, and links to
 pages that have more in-depth information on how these operators work and how particular language-specific
 ReactiveX versions have implemented these operators.