docs(*.md) update general docs

README.md

@@ -1,43 +1,45 @@
 # react-redux-composable-list
 
-The react-redux-composable-list offers you a solution to show a list of items. That sounds simple. Why would you need a library to deal with it?
+The react-redux-composable-list offers you a solution to display a list of complex items. That sounds simple. Why would you need a library to deal with it?
 
-The library comes with various opt-in features to manipulate the list of items or to change the representation of the list. These opt-in features are called enhancements or to stay in the React world: higher order components. Multiple enhancements can be composed to opt-in multiple features like sorting, filtering or pagination. After all, it gives you only an entry point to these enhancements. You can come up with enhancements on your own, since these enhancements are reusable and composable and the library API is well documented.
+The library comes with various opt-in features to manipulate the list of items or to change the representation of the list. These opt-in features are called **enhancements** or to stay in the React world: higher order components. Multiple enhancements can be composed to opt-in multiple features like **sorting, filtering or pagination**. After all, it gives you only an entry point to these enhancements. You can come up with enhancements on your own and just compose them into the set of enhancements that come with the library.
 
-In addition, in order to manipulate the state of those enhancements, you can use built-in enhancer components. They can be used everywhere in your application and allow you to manipulate sorting, filtering etc. There again the library stays extendable. You can write your own enhancer components.
+In addition, in order to manipulate the state of those enhancements, you can use (built-in) **enhancer** components. They can be used everywhere in your application and allow you to manipulate the sorting, filtering etc. state. There again the library stays extendable. You can write your own enhancer components.
 
 ![Demo](https://media.giphy.com/media/xUOrvUtfjt2EhMUjvi/giphy.gif)
 
-With the mental model behind this [idea](https://github.com/SmallImprovements/react-redux-composable-list/blob/master/docs/Idea.md) and [concepts](https://github.com/SmallImprovements/react-redux-composable-list/blob/master/docs/Concepts.md), you can come up with great features on your own. All features can be used to be composed into each other. The library comes with several features that you can already use, but it is not bound to a rigid endgame solution.
+With the mental model behind this [idea](https://rwieruch.gitbooks.io/react-redux-composable-list/docs/Idea.html) and [concepts](https://rwieruch.gitbooks.io/react-redux-composable-list/docs/Concepts.html), you can come up with great opt-in features on your own. All features, coming from the library or from yourself, can be used to be composed into each other. The library comes with several features that you can already use, but it is not bound to a rigid endgame solution.
 
 ## Demo
 
 You can checkout the live demonstrations ([Showcases](https://react-redux-composable-list-showcases.wieruch.com/), [Real World](https://react-redux-composable-list-realworld.wieruch.com/)) that show several features of the library.
 
-In addition, you can checkout the [examples/](https://github.com/SmallImprovements/react-redux-composable-list/tree/master/examples) folder in the GitHub repository. In each of them you will find instructions to set up the each project. You can try them by cloning the whole library repository
+In addition, you can checkout the [examples/](https://github.com/SmallImprovements/react-redux-composable-list/tree/master/examples) folder in the GitHub repository. In each sub folder you will find instructions to set up the demonstrated project.
 
 ## Why should you use it?
 
-The react-redux-composable-list solved a real problem for us at Small Improvements. After the implementation, we were able to show lists of items in tables and to opt-in multiple features. In the end, we think we are not the only ones who need this common set of features in such a composable and extendable way.
+The react-redux-composable-list solved a real problem for us at [Small Improvements](https://www.small-improvements.com/). By using this approach, we were able to display lists of items in a powerful yet flexible way. It always depends on your use case if you want to add a powerful set of features to your displayed list (pagination, filter, sorting) or if you want to keep it simple by only adding the selection feature.
 
-### Composeable
+In the end, we thought we are not the only ones who need this common set of features in such a composable and extendable way.
 
-The library builds up on the React concept of composeability. You can weave multiple higher order components into each other to manipulate your list, for instance with sorting, or to alter the final representation of the list, for instance with pagination.
+### Composable
+
+The library builds up on the React concept of composability. You can weave multiple higher order components into each other to manipulate your list, for instance with sorting, or to alter the final representation of the list, for instance with pagination.
 
 ### Extendable
 
-Since the library API to the Redux store is documented, you can come up with your own enhancements and enhancer (higher order) components. Only a few enhancements and enhancers come with the library. Yet, with the mental model behind it, you can extend the feature set of the library.
+Since the library API, that is basically an API for your Redux store, is well documented, you can come up with your own enhancements and enhancer components. Only a few enhancements and enhancers come with the library. Yet, with the mental model behind it, you can extend the feature set of the library on your own.
 
 ### Built-in Features
 
-The library comes already with several features like sorting, filtering, pagination, extendable columns and selecting of items. These are common features in a list of items. But you can come up with your own opt-in features.
+The library comes already with several features like sorting, filtering, pagination, extendable columns and selecting of items. These are common features when displaying a list of items. But you can come up with your own opt-in features as well.
 
 ## Getting Started
 
 If you want to jump right away into using the library, you should checkout the [Getting Started](https://rwieruch.gitbooks.io/react-redux-composable-list/docs/GettingStarted.html) section in the documentation.
 
-Apart from that you should checkout the whole [documentation](https://rwieruch.gitbooks.io/react-redux-composable-list) to get to know what is the library about and how to use it.
+If you want to dive deeper into the library, you can checkout the whole [documentation](https://rwieruch.gitbooks.io/react-redux-composable-list) to get to know what the library is about and how to use it.
 
 ## Contribute
 
-Please let us know if you have any feedback. You can create Issues to give feedback or to contribute improvements. Read the [contribution guidelines](/docs/Contribute.md).
+Please let us know if you have any feedback. The repository is open for contribution, please read the [contribution guidelines](/docs/Contribute.md).

docs/Concepts.md

@@ -27,17 +27,17 @@ A **conditional rendering** could be to show a placeholder when the list is empt
 
 An **extension** of the basic component could be pagination. Whenever you see a paginated list of data, you get controls to navigate through the pages. It can be useful for huge lists of data. The extension would wrap around the basic component to give you these controls.
 
-Composeability makes it possible to enhance a component. You can use the third-party library [recompose](https://github.com/acdlite/recompose) to compose multiple enhancements into an enhanced component.
+Composability makes it possible to enhance a component. You can use the third-party library [recompose](https://github.com/acdlite/recompose) to compose multiple enhancements into an enhanced component.
 
 ### Enhanced Component
 
-Your enhanced component can show the list of data in any way. After all, it only gets a (manipulated) list of data. However, a list of items is shown most of the time in a kind of table component. That's why the library comes with useful components to compose a table of data. A natural wrapper component, the Enhanced Component, is used to identify the component and can be used to opt-in more features. In addition, the library provides you with Row, Cell and HeaderCell components to layout your enhanced component. But as mentioned, you don't need to use them apart from the Enhanced Component.
+Your enhanced component can show the list of data in any way. After all, it only gets a (manipulated) list of data. However, a list of items is shown most of the time in a kind of table component. That's why the library comes with useful components to compose a table of data. A mandatory wrapper component, the Enhanced Component, is used to identify the applied enhancements with a state key. In addition, the library provides you with Row, Cell and HeaderCell components to layout your enhanced component. But as mentioned, you don't need to use them apart from the Enhanced Component.
 
 ### Enhancer Components
 
 In addition, there are enhancer components. They can be used inside or outside of your enhanced component. In fact, they can be used anywhere in your application. They will be responsible to alter enhancements. These enhancements will be stored and flow back to the enhanced component via its composed enhancements.
 
-There are several active enhancer that already come with the library. However, since the library builds up on composeability, you can use your own enhancer components too. There is an library API to manipulate the enhancements in the store by using Redux actions. You can write your own enhancer components.
+There are several active enhancer that already come with the library. However, since the library builds up on extendability, you can use your own enhancer components too. There is a library API to manipulate the enhancements in the Redux store by using Redux actions. So you can write your own enhancer components that lead to changes in (built-in) enhancements.
 
 ## The Flow
 

docs/Demo.md

@@ -1,5 +1,5 @@
 # Demo
 
-You can checkout the live demonstrations ([Showcases](https://react-redux-composable-list-showcases.wieruch.com/), [Real World](https://react-redux-composable-list-realworld.wieruch.com/)) that demonstrate several features of the library.
+You can checkout the live demonstrations ([Showcases](https://react-redux-composable-list-showcases.wieruch.com/), [Real World](https://react-redux-composable-list-realworld.wieruch.com/)) that show several features of the library.
 
-In addition, you can checkout the [examples/](https://github.com/SmallImprovements/react-redux-composable-list/tree/master/examples) folder in the GitHub repository. In each of them you will find instructions to set up each project.
+In addition, you can checkout the [examples/](https://github.com/SmallImprovements/react-redux-composable-list/tree/master/examples) folder in the GitHub repository. In each sub folder you will find instructions to set up the demonstrated project.

docs/GettingStarted.md

@@ -2,9 +2,9 @@
 
 You can use npm to install the library: `npm install react-redux-composable-list`
 
-There are **two requirements** in order to use the library.
+There are **two requirements** in order to use the library:
 
-First, since it depends to store the state in the Redux store, you have to connect the library reducers to your Redux store.
+First, since it depends to save the state in the Redux store, you have to connect the reducers provided by the library to your Redux store.
 
 ```javascript
 import { createStore, combineReducers } from 'redux';
@@ -21,7 +21,7 @@ const configureStore = (initialState) => createStore(rootReducer, initialState);
 export default configureStore;
 ```
 
-Second, you need to use the [react-redux](https://github.com/reactjs/react-redux) Provider component, that takes the your Redux store as input, in a top level component. Maybe you already do so, because you have a React + Redux application. Afterwards you can use the functionalities of the library in your component tree.
+Second, you need to use the [react-redux](https://github.com/reactjs/react-redux) Provider component, that takes your Redux store as input, in a top level component. Maybe you already do so, because you have a React + Redux application. Afterward, you can use the functionalities of the library in your component tree.
 
 ```javascript
 import configureStore from 'path/to/store';
@@ -34,7 +34,7 @@ const store = configureStore(initialState);
 </Provider>
 ```
 
-Now you can start to write your first [plain](/docs/features/Plain.md) component.
+Now you can start to write your first [plain](/docs/features/Plain.md) component:
 
 ```javascript
 import { components } from 'react-redux-composable-list';
@@ -53,7 +53,7 @@ const Plain = ({ list, stateKey }) =>
 export default Plain;
 ```
 
-And use it in your application.
+And use it in your application:
 
 ```javascript
 import Plain from path/to/component';
@@ -70,15 +70,17 @@ const App = () =>
   />
 ```
 
-That's it. You show the list of data. But that's boring, because you want to use an Enhancement to manipulate your data. Otherwise the library doesn't bring you any benefit. Let's define an Enhanced Component that enables you to select items from the list.
+That's it. You show the list of data. But that's dull, isn't it? You might want to use the functionalities of the library. There should be an enhancement ([higher order component](https://www.robinwieruch.de/gentle-introduction-higher-order-components/)) in between, otherwise the library doesn't bring you any benefits.
+
+Let's define an Enhanced Component that enables you to select items from the list:
 
 ```javascript
 import { components, enhancements } from 'react-redux-composable-list';
 const { Enhanced, Row, Cell } = components;
 const { withSelectables } = enhancements;
 
-const Selectable = ({ list, stateKey, isSelectable }) =>
-  <Enhanced stateKey={stateKey} isSelectable={isSelectable}>
+const Selectable = ({ list, stateKey }) =>
+  <Enhanced stateKey={stateKey}>
     {list.map(item =>
       <Row key={item.id}>
         <Cell style={{ width: '70%' }}>{item.title}</Cell>
@@ -87,10 +89,10 @@ const Selectable = ({ list, stateKey, isSelectable }) =>
     )}
   </Enhanced>
 
-export default withSelectables({ ids: [] })(Selectable);
+export default withSelectables()(Selectable);
 ```
 
-The object that is passed to the Enhancement is used to configure the Enhancement. In that case, the `ids` array is empty, but you could pass `['1']` to initially select the item with the `id: '1'`. Now you can use it again in your application.
+That should already do the magic to make your items in the list selectable. You can use it again in your application:
 
 ```javascript
 import Selectable from path/to/component';
@@ -107,6 +109,14 @@ const App = () =>
   />
 ```
 
-That's it. Your items in the list should be selectable now. Refer to the [Select enhancement](/docs/features/Select.md) to get to know more about it. After all, you would need to retrieve the selected items at some point to do further things.
+The enhancement can be configured by passing an configuration object.  You could pass `['1']` to initially select the item with the `id: '1'`:
+
+```javascript
+...
+
+export default withSelectables({ ids: ['1'] })(Selectable);
+```
+
+That's it. Your items in the list should be selectable now. Optionally you can have already selected items. Refer to the [Select enhancement](/docs/features/Select.md) to get to know more about it. After all, you would need to retrieve the selected items at some point to do further things.
 
 Before you dive into the set of features of the library, you should read the [Concepts](/docs/Concepts.md) behind it.

docs/Idea.md

@@ -1,8 +1,8 @@
 # Idea
 
-React has several great concepts and patterns that can be used to achieve a flexible yet sophisticated approach to show and manipulate data. The main idea behind the library is composeability.
+React has several great concepts and patterns that can be used to achieve a flexible yet sophisticated approach to show and manipulate data. The main idea behind the library is composability.
 
-On the one hand higher order components (HOCs) can be used and re-used to **opt-in various enhancements**. A basic component, that simply shows a list of items, can become an enhanced version of the component. The enhancement could be to make the list filterable or sortable. Or it could be to add the ability to select items from the list. These opt-in enhancements can get stacked by using composition. Multiple enhancements have a compound effect of features on your basic component. With composition the library enables you to sort, filter and paginate your list.
+On the one hand, [higher order components](https://www.robinwieruch.de/gentle-introduction-higher-order-components/) (HOCs) can be used and re-used to **opt-in various enhancements**. A basic component, that simply shows a list of items, can become an enhanced version of the component. The enhancement could be to make the list filterable or sortable. Or it could be to add the ability to select items from the list. These opt-in enhancements can get stacked by using composition. Multiple enhancements have a compound effect of features on your basic component. With composition the library enables you to sort, filter and paginate your list.
 The library comes with various in-house enhancements, but you can opt-in your own higher order components.
 
-On the other hand, the children property keeps the components that show the data composeable, reusable and extendable. It's not one component that takes a big configuration object. You can **decide on your own what you want to do with the data** that comes from all your opt-in enhancements. You can show it in a table layout, but you are not forced to. Yet it is a common way to show a lot of data in a table to keep it accessible. That's why the library comes with a bunch of in-house components to layout a table. These components are used to show the data. But you can of course use your own components too.
+On the other hand, the children property keeps the components that show the data composable, reusable and extendable. It's not one component that takes a big configuration object. You can **decide on your own what you want to do with the data** that comes from all your opt-in enhancements. You can show it in a table layout, but you are not forced to. Yet it is a common way to show a lot of data in a table to keep it accessible. That's why the library comes with a bunch of in-house components to layout a table. These components are used to show the data. But you can of course use your own components too.