docs: gitbook

docs/README.md

@@ -23,6 +23,13 @@ The current version of `ngrx-entity-relationship` has been tested and can be use
 - NGRX 7
 - NGRX 6
 
+**Need help or have a suggestion?**
+
+- [chat on gitter](https://gitter.im/ngrx-entity-relationship/community)
+- [ask a question on stackoverflow for Redux solution](https://stackoverflow.com/questions/ask?tags=ngrx-entity-relationship%20ngrx%20angular)
+- [ask a question on stackoverflow for NGRX solution](https://stackoverflow.com/questions/ask?tags=ngrx-entity-relationship%20redux%20reactjs)
+- [report an issue on GitHub](https://github.com/satanTime/ngrx-entity-relationship/issues/new)
+
 ## Problem of normalized entities and their relationships in Redux and NGRX
 
 Let's imagine that we have the next models:

docs/api/core/childentity-function.md

@@ -1,5 +1,5 @@
 ---
-description: childEntity function
+description: Information about childEntity function and how to create relationship selectors
 ---
 
 `childEntity` is a **relationship selector factory**,
@@ -16,14 +16,14 @@ declare function childEntity(
 );
 ```
 
-- `entityStateSelector` - is an **entity state selector** of a desired entity.
-- `keyId` - a property name in the related entity which points to the id of the parent entity. (Address.id -> Company.addressId)
-- `keyValue` - a property name in the parent entity where the related entity should be assigned.
+- `entityStateSelector` - is an [**entity state selector**](entity-state-selector.md) of a desired entity.
+- `keyId` - a property name in the related entity which points to the id of the parent entity, `addressId` from `Address.id -> Company.addressId`.
+- `keyValue` - a property name in the parent entity where the related entity should be assigned, `company` from `Address.company`.
 - `relationships` - is an optional parameter which accepts **relationship selectors** for the related entity.
 
 An example is the `Address`. Its model has `company`, but does not have `companyId`.
 However, `Company` entity has `addressId`.
-Therefore, if we want a selector which fetches an address with its company it might look like:
+Therefore, if we want a **root selector** which fetches an address with its company it might look like:
 
 ```ts
 const address = rootEntity(

docs/api/core/childentityselector-function.md

@@ -1,9 +1,9 @@
 ---
-description: childEntitySelector function
+description: Information about childEntitySelector function and how to create preconfigured relationship selector factories based on childEntity
 ---
 
 `childEntitySelector` is a function which creates a predefined **relationship selector factory**.
-The goal here is to simply the process of creating **relationship selectors** with [`childEntity`](#childentity-function).
+Its goal is to simply the process of creating **relationship selectors** with [`childEntity`](childentity-function.md).
 
 ```ts
 declare function childEntitySelector(
@@ -13,7 +13,7 @@ declare function childEntitySelector(
 );
 ```
 
-It's parameters are the same as [`childEntity`](#childentity-function) has, but without relationships.
+Its parameters are the same as [`childEntity`](childentity-function.md) has, but without relationships.
 
 ```ts
 const address = rootEntitySelector(

docs/api/core/childrenentities-function.md

@@ -1,5 +1,5 @@
 ---
-description: childrenEntities function
+description: Information about childrenEntities function and how to create relationship selectors
 ---
 
 `childrenEntities` is a **relationship selector factory**,
@@ -16,14 +16,14 @@ declare function childrenEntities(
 );
 ```
 
-- `entityStateSelector` - is an **entity state selector** of a desired entity.
-- `keyId` - a property name in the related entity which points to the id of the parent entity. (Company.id -> User.companyId)
-- `keyValue` - a property name in the parent entity where the array of related entities should be assigned.
+- `entityStateSelector` - is an [**entity state selector**](entity-state-selector.md) of a desired entity.
+- `keyId` - a property name in the related entity which points to the id of the parent entity, `companyId` from `Company.id -> User.companyId`.
+- `keyValue` - a property name in the parent entity where the array of related entities should be assigned, `stuff` from `Company.stuff`.
 - `relationships` - is an optional parameter which accepts **relationship selectors** for the related entities.
 
 An example is the `Company`. Its model has `staff`, but does not have `staffId`.
 However, `User` entity has `companyId`.
-Therefore, if we want a selector which fetches a company with its staff it might look like:
+Therefore, if we want a **root selector** which fetches a company with its staff it might look like:
 
 ```ts
 const company = rootEntity(

docs/api/core/childrenentitiesselector-function.md

@@ -1,9 +1,9 @@
 ---
-description: childrenEntitiesSelector function
+description: Information about childrenEntitiesSelector function and how to create preconfigured relationship selector factories based on childrenEntities
 ---
 
 `childrenEntitiesSelector` is a function which creates a predefined **relationship selector factory**.
-The goal here is to simply the process of creating **relationship selectors** with [`childrenEntities`](#childrenentities-function).
+Its goal is to simply the process of creating **relationship selectors** with [`childrenEntities`](childrenentities-function.md).
 
 ```ts
 declare function childrenEntitiesSelector(
@@ -13,7 +13,7 @@ declare function childrenEntitiesSelector(
 );
 ```
 
-It's parameters are the same as [`childrenEntities`](#childrenentities-function) has, but without relationships.
+Its parameters are the same as [`childrenEntities`](childrenentities-function.md) has, but without relationships.
 
 ```ts
 const company = rootEntitySelector(

docs/api/core/entity-state-selector.md

@@ -1,15 +1,15 @@
 ---
-description: Entity state selector
+description: Information about how an entity state selector should look like in order to be used with ngrx-entity-relationship
 ---
 
 An **entity state selector** can be:
 
-- a function that returns `EntityState<T>`
-- an instance of `EntityCollectionService<T>`
-- an instance of `EntityCollectionServiceBase<T>`
-- an object `{collection: selector, id: selector}`
+- an object which contains selectors `{collection: selector, id: selector}`
+- a function that returns [`EntityState<T>`](https://ngrx.io/api/entity/EntityState) like in **NGRX**
+- an instance of [`EntityCollectionService<T>`](https://ngrx.io/api/data/EntityCollectionService) like in **NGRX**
+- an instance of [`EntityCollectionServiceBase<T>`](https://ngrx.io/api/data/EntityCollectionServiceBase) like in **NGRX** 
 
-The last case is useful when the `id` key of an entity isn't `id`, but another one: `Id`, `uuid`, etc.
+The first case is useful when the `id` key of an entity is not `id`, but another one: `Id`, `uuid`, etc.
 Then you can define here the key name, or a function which returns its value from an entity.
 
 ```ts

docs/api/core/relatedentity-function.md

@@ -1,5 +1,5 @@
 ---
-description: relatedEntity function
+description: Information about relatedEntity function and how to create relationship selectors
 ---
 
 `relatedEntity` is a **relationship selector factory**,
@@ -16,17 +16,17 @@ declare function relatedEntity(
 );
 ```
 
-- `entityStateSelector` - is an **entity state selector** of a desired entity.
-- `keyId` - a property name in the parent entity which points to the id of the related entity. (User.companyId -> Company.id)
-- `keyValue` - a property name in the parent entity where the related entity should be assigned.
+- `entityStateSelector` - is an [**entity state selector**](entity-state-selector.md) of a desired entity.
+- `keyId` - a property name in the parent entity which points to the id of the related entity, `companyId` from `User.companyId -> Company.id`.
+- `keyValue` - a property name in the parent entity where the related entity should be assigned, `company` from `User.company`
 
   > if `keyId` is an array of ids, then `keyValue` has to be an array of the related entities too.
 
-- `relationships` - is an optional parameter which accepts **relationship selectors** for the related entity.
+- `relationships` - is an optional parameter which accepts **relationship selectors** for the parent entity.
 
 An example is the `User`. Its model has `companyId`, `company`,
 and there is `selectCompanyState` that returns `EntityState<Company>`.
-Therefore, if we want a selector which fetches a user with its company it might look like:
+Therefore, if we want a **root selector** which fetches a user with its company it might look like:
 
 ```ts
 const user = rootEntity(

docs/api/core/relatedentityselector-function.md

@@ -1,9 +1,9 @@
 ---
-description: relatedEntitySelector function
+description: Information about relatedEntitySelector function and how to create preconfigured relationship selector factories based on relatedEntity
 ---
 
 `relatedEntitySelector` is a function which creates a predefined **relationship selector factory**.
-The goal here is to simply the process of creating **relationship selectors** with [`relatedEntity`](#relatedentity-function).
+Its goal is to simply the process of creating **relationship selectors** with [`relatedEntity`](relatedentity-function.md).
 
 ```ts
 declare function relatedEntitySelector(
@@ -13,7 +13,7 @@ declare function relatedEntitySelector(
 );
 ```
 
-It's parameters are the same as [`relatedEntity`](#relatedentity-function) has, but without relationships.
+Its parameters are the same as [`relatedEntity`](relatedentity-function.md) has, but without relationships.
 
 ```ts
 const user = rootEntitySelector(

docs/api/core/rootentities-function.md

@@ -1,15 +1,17 @@
 ---
-description: rootEntities function
+description: Information about rootEntities function and how to create root selectors for arrays of entities
 ---
 
 `rootEntities` is a **root selector factory** which helps to fetch an array of entities.
-its call produces a **root selector** which can be used with **Redux** and **NGRX**.
+It requires a **root selector factory** and
+produces a **root selector** which selects an array of entities.
+It can be used with **Redux** and **NGRX**.
 
 ```ts
 declare function rootEntities(rootSelector);
 ```
 
-- `rootSelector` - is a **root selector** which has been produced by `rootEntity` function.
+- `rootSelector` - is a **root selector** which has been produced by [`rootEntity`](rootentity-function.md) function.
 
 ```ts
 const selectUsers = rootEntities(selectUser);

docs/api/core/rootentity-function.md

@@ -1,9 +1,9 @@
 ---
-description: rootEntity function
+description: Information about rootEntity function and how to create root selectors
 ---
 
 `rootEntity` is a **root selector factory**,
-its call produces a **root selector** which can be used with **Redux** and **NGRX**.
+its call produces a **root selector** which can be used with **Redux** and **NGRX** in order to select related entities.
 
 ```ts
 declare function rootEntity(
@@ -13,9 +13,9 @@ declare function rootEntity(
 );
 ```
 
-- `entityStateSelector` - is an **entity state selector** of a desired entity.
+- `entityStateSelector` - is an [**entity state selector**](entity-state-selector.md) of a desired entity.
 
-- `transformer` - is an optional function which can be useful if we need a post processing transformation,
+- `transformer` - is an optional function which can be useful if we need a [post processing transformation](../../guide/transform-entities.md),
   for example, to a class instance, basically an entity can be transformed to anything.
 
   ```ts

docs/api/core/rootentityselector-function.md

@@ -1,9 +1,9 @@
 ---
-description: rootEntitySelector function
+description: Information about rootEntitySelector function and how to create preconfigured root selector factories based on rootEntity
 ---
 
 `rootEntitySelector` is a function which creates a predefined **root selector factory**.
-The goal here is to simply the process of creating **root selectors** with [`rootEntity`](#rootentity-function).
+Its goal is to simply the process of creating **root selectors** with [`rootEntity`](rootentity-function.md).
 
 ```ts
 declare function rootEntitySelector(
@@ -12,7 +12,7 @@ declare function rootEntitySelector(
 );
 ```
 
-It's parameters are the same as [`rootEntity`](#rootentity-function) has, but without relationships.
+Its parameters are the same as [`rootEntity`](rootentity-function.md) has, but without relationships.
 
 ```ts
 const user = rootEntitySelector(selectUserState);

docs/api/graphql/mutations.md

@@ -1,9 +1,9 @@
 ---
-description: Mutations with GraphQL, Redux and NGRX
+description: Information how to create mutation queries for GraphQL in Redux and NGRX
 ---
 
-`toGraphQL` is not enough to generate a mutation query.
-The library provides a helper function called `toMutation` which solves the issue.
+[`toGraphQL`](../../guide/graphql/quick.md) is not enough to generate a mutation query.
+`ngrx-entity-relationship` provides a helper function called `toMutation` which solves the issue.
 
 For example
 
@@ -40,7 +40,7 @@ mutation {
 }
 ```
 
-With `Apollo` service, it can be used like that
+With **Apollo service**, it can be used like that
 
 ```ts
 apollo.mutate({

docs/api/graphql/queries.md

@@ -1,15 +1,15 @@
 ---
-description: Queries with GraphQL, Redux and NGRX
+description: Information how to create queries with variables for GraphQL in Redux and NGRX
 ---
 
-`toGraphQL` is not enough to generate a query with variables.
-The library provides a function called `toQuery` which solves the issue.
+[`toGraphQL`](../../guide/graphql/quick.md) is not enough to generate a query with variables.
+`ngrx-entity-relationship` provides a function called `toQuery` which solves the issue.
 
 All [`toQuery`](#queries-with-graphql-redux-and-ngrx),
 [`toSubscription`](#subscriptions-with-graphql-redux-and-ngrx)
 and [`toMutation`](#mutations-with-graphql-redux-and-ngrx) support variables.
 They can be passed as the first parameter.
-`toGraphQL` supports `$` to define variables instead of values.
+[`toGraphQL`](../../guide/graphql/quick.md) supports `$` to define variables instead of values.
 
 ```ts
 apollo.mutate({

docs/api/graphql/subscriptions.md

@@ -1,14 +1,16 @@
 ---
-description: Subscriptions with GraphQL, Redux and NGRX
+description: Information how to create subscription queries for GraphQL in Redux and NGRX
 ---
 
-`toGraphQL` is not enough to generate a subscription query.
-The library provides a helper function called `toSubscription` to solve the issue.
+[`toGraphQL`](../../guide/graphql/quick.md) is not enough to generate a subscription query.
+`ngrx-entity-relationship` provides a helper function called `toSubscription` to solve the issue.
 
 For example
 
 ```ts
-const query = toSubscription(toGraphQL('users', action.selector));
+const query = toSubscription(
+  toGraphQL('users', action.selector),
+);
 ```
 
 will generate
@@ -22,7 +24,7 @@ subscription {
 }
 ```
 
-With `Apollo` service, it can be used like that
+With **Apollo service**, it can be used like that
 
 ```ts
 apollo.subscribe({

docs/api/rootentityflags-options.md

@@ -1,9 +1,9 @@
 ---
-description: rootEntityFlags options
+description: Special options in rootEntityFlags for more precise behavior
 ---
 
-There is a flag `rootEntityFlags.disabled` that may be useful for disabling selectors during updates of entities
-in order to avoid unwanted triggers of selectors.
-Simply set it to `true` before you start update and back to `false` afterwards.
+There is a flag `rootEntityFlags.disabled` that may be useful to disable selectors during updates of entities
+in order to avoid unwanted triggers of them.
+Simply set it to `true` before you start an update and back to `false` afterwards.
 
-**When you set it back to `false` you need to shake the store to get updated entities in selectors**.
+**When you set it back to `false` you need to shake the store to get updated entities in related selectors**.

docs/api/rxjs/relationships.md

@@ -1,18 +1,18 @@
 ---
-description: relationships pipe operator
+description: Information about relationships pipe operator which helps to extend entities with their relationships in observable data streams
 ---
 
-`relationships` is a RxJS pipe operator which is useful when we already have a stream of existing entities
+`relationships` is a [RxJS pipe operator](https://rxjs-dev.firebaseapp.com/guide/operators) which is useful when we already have a stream of existing entities
 and would like to extend them with relationships.
 
 For that we need:
 
 - the `store` object
-- a **root selector** we want to apply
+- a **root selector** with relationships we want to apply
 - an observable stream of entities
 
-Let's pretend we have a `user$` stream which emits a user entity time to time.
-Then we could extend it with the next operation.
+Let's pretend that we have a `user$` stream which emits a user entity time to time.
+Then, we could extend the emitted entity in the next way in order to get it with relationships.
 
 ```ts
 const userWithRelationships$ = user$.pipe(
@@ -22,8 +22,8 @@ const userWithRelationships$ = user$.pipe(
 );
 ```
 
-The same can be done for a stream that emits an array of users.
-In this case the **root selector** for arrays should be used.
+The same can be done for a stream which emits an array of users.
+In this case, the **root selector** for arrays should be used.
 
 ```ts
 const usersWithRelationships$ = users$.pipe(

docs/extra/releasing-cache.md

@@ -1,11 +1,11 @@
 ---
-description: Releasing cache
+description: Information how to release cache from root selectors
 ---
 
-Every function of the library which produces selectors returns a shape that has `release` function.
+Every function of the library which produces selectors returns a shape that has the `release` function.
 Its behavior and purpose is the same as
-[Memoized Selectors](https://ngrx.io/guide/store/selectors#resetting-memoized-selectors) of `@ngrx/store`.
-Once you do not need a selector simply call `release` to reset the memoized value.
+[Memoized Selectors](https://ngrx.io/guide/store/selectors#resetting-memoized-selectors) from `@ngrx/store`.
+Once you do not need a selector simply call `release` to reset the cached entity.
 
 ```ts
 const selectUser = rootEntity(selectUserState);