Add additional explanation and details for compose package

packages/compose/README.md

@@ -2,6 +2,52 @@
 
 The `compose` package is a collection of handy [Higher Order Components](https://facebook.github.io/react/docs/higher-order-components.html) (HOCs) you can use to wrap your WordPress components and provide some basic features like: state, instance id, pure...
 
+
+The **compose** function is an alias to flowRight from Lodash. It comes from functional programming world and allows to compose any number of functions. An example that illustrates it for two functions:
+
+```js
+const compose = ( f, g ) => x
+    => f( g( x ) );
+```
+
+Here's a simplified example of **compose** in use from our code, see [plugin-sidebar](https://github.com/WordPress/gutenberg/blob/master/packages/edit-post/src/components/sidebar/plugin-sidebar/index.js) for full code:
+
+Using compose:
+
+```js
+const applyWithSelect = withSelect( ( select, ownProps ) => {
+	return doSomething( select, ownProps);
+} );
+const applyWithDispatch = withDispatch( ( dispatch, ownProps ) => {
+	return doSomethingElse( dispatch, ownProps );
+} );
+
+export default compose(
+	withPluginContext,
+	applyWithSelect,
+	applyWithDispatch,
+)( PluginSidebarMoreMenuItem );
+```
+
+Equivalent to the following without compose:
+
+```js
+const applyWithSelect = withSelect( ( select, ownProps ) => {
+	return doSomething( select, ownProps);
+} );
+const applyWithDispatch = withDispatch( ( dispatch, ownProps ) => {
+	return doSomethingElse( dispatch, ownProps );
+} );
+
+export default withPluginContext(
+	applyWithSelect(
+		applyWithDispatch(
+			PluginSidebarMoreMenuItem
+		)
+	)
+);
+```
+
 ## Installation
 
 Install the module
@@ -14,6 +60,8 @@ _This package assumes that your code will run in an **ES2015+** environment. If
 
 ## Usage
 
+An example using the HOC `withInstanceId` from the compose package:
+
 ```js
 import { withInstanceId } from '@wordpress/compose';
 
@@ -24,6 +72,5 @@ function WrappedComponent( props ) {
 const ComponentWithInstanceIdProp = withInstanceId( WrappedComponent );
 ```
 
-Refer to each Higher Order Component's README file for more details.
+Refer to each Higher Order Component's README file for more details, see [list of components](https://github.com/WordPress/gutenberg/tree/master/packages/compose/src).
 
-<br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>