diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1af19ab..75a8a5e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,7 @@
+## [1.0.2] 10.07.2022
+
+* improve documentation
+
 ## [1.0.1] 04.07.2022
 
 * provide example project
diff --git a/README.md b/README.md
index 094b06a..3d29b93 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,81 @@
-<img src=".github/thumbnail.png"/>
+<img src="https://github.com/mi-sch-ka/rx-state-machine/blob/main/.github/thumbnail.png?raw=true"/>
     
 [![Pub](https://img.shields.io/pub/v/rx_state_machine.svg)](https://pub.dartlang.org/packages/rx_state_machine)
 
 A library for finite state machine realization in Dart. Inspired by [Tinder StateMachine library](https://github.com/Tinder/StateMachine).
+
+# How to use
+
+Define states, events and side effects:
+
+```dart
+
+abstract class State {}
+class Open extends State {}
+class Closed extends State {}
+
+
+abstract class Event {}
+class OnOpening extends Event {}
+class OnClosing extends Event {}
+
+
+abstract class SideEffect {
+  void call(State state, Event event);
+}
+
+class MakeSomeNoise extends SideEffect {
+  @override
+  void call(State state, Event event) => print("Ka-chunk-creeeeeeak-squeekie-squeekie");
+}
+```
+
+Initialize state machine and declare state transitions:
+
+```dart
+final RxStateMachine<State, Event, SideEffect> _stateMachine =
+    RxStateMachine<State, Event, SideEffect>.create((g) => g
+      ..initialState(Open())
+      ..state<Open>((b) => b
+        ..on<OnClosing>((state, event) {
+          return b.transitionTo(Closed(), MakeSomeNoise());
+        }))
+      ..state<Closed>((b) => b
+        ..on<OnOpening>((state, event) {
+          return b.transitionTo(Open(), MakeSomeNoise());
+        }))
+      ..onTransition((transition) {
+        if (transition is Valid) {
+          final item = transition as Valid;
+          print("Valid transition: from [${item.fromState}] to [${item.toState}] by [${item.event}]");
+          if(item.sideEffect is SideEffect) {
+            item.sideEffect(item.toState, item.event);
+          }
+        } else if (transition is Invalid) {
+          final item = transition as Invalid;
+          print("Invalid transition: from [${item.fromState}] by [${item.event}]");
+        }
+      })
+);
+```
+
+Observe the machine and react to changes.
+
+```dart
+_stateMachine.states.listen((state) {
+    if(state is Open && !_security.authenticated()) {
+      _security.alarm();
+    }
+  });
+```
+
+Perform state transitions:
+
+```dart
+  _stateMachine.transition(new OnClosing());
+  //...
+  _stateMachine.transition(new OnOpening());
+```
+
+
+
diff --git a/pubspec.yaml b/pubspec.yaml
index c6089f4..ef90384 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,7 +1,7 @@
 name: rx_state_machine
 description: >-
   A library for finite state machine realization in Dart similar to the [Tinder StateMachine library](https://github.com/Tinder/StateMachine).
-version: 1.0.1
+version: 1.0.2
 homepage: https://github.com/mi-sch-ka
 repository: https://github.com/mi-sch-ka/rx-state-machine
 issue_tracker: https://github.com/mi-sch-ka/rx-state-machine/issues