diff --git a/docs/extensions/guides/README.md b/docs/extensions/guides/README.md
index 2917090212..2f04edfea1 100644
--- a/docs/extensions/guides/README.md
+++ b/docs/extensions/guides/README.md
@@ -19,10 +19,11 @@ Each guide or sample will include:
 | [Stores](stores.md) | |
 | [Components](components.md) | |
 | [KubeObjectListLayout](kube-object-list-layout.md) | |
+| [Working with mobx](working-with-mobx.md) | |
 
 ## Samples
 
 | Sample | APIs |
 | ----- | ----- |
 [helloworld](https://github.com/lensapp/lens-extension-samples/tree/master/helloworld-sample) | LensMainExtension <br> LensRendererExtension <br> Component.Icon <br> Component.IconProps |
-[minikube](https://github.com/lensapp/lens-extension-samples/tree/master/minikube-sample) | LensMainExtension <br> Store.clusterStore <br> Store.workspaceStore |
\ No newline at end of file
+[minikube](https://github.com/lensapp/lens-extension-samples/tree/master/minikube-sample) | LensMainExtension <br> Store.clusterStore <br> Store.workspaceStore |
diff --git a/docs/extensions/guides/working-with-mobx.md b/docs/extensions/guides/working-with-mobx.md
new file mode 100644
index 0000000000..5577ff6bdc
--- /dev/null
+++ b/docs/extensions/guides/working-with-mobx.md
@@ -0,0 +1,23 @@
+# Working with mobx
+
+## Introduction
+
+Lens uses `mobx` as its state manager on top of React's state management system.
+This helps with having a more declarative style of managing state, as opposed to `React`'s native `setState` mechanism.
+You should already have a basic understanding of how `React` handles state ([read here](https://reactjs.org/docs/faq-state.html) for more information).
+However, if you do not, here is a quick overview.
+
+- A `React.Component` is generic over both `Props` and `State` (with default empty object types).
+- `Props` should be considered read-only from the point of view of the component and is the mechanism for passing in "arguments" to a component.
+- `State` is a component's internal state and can be read by accessing the parent field `state`.
+- `State` **must** be updated using the `setState` parent method which merges the new data with the old state.
+- `React` does do some optimizations around re-rendering components after quick successions of `setState` calls.
+
+## How mobx works:
+
+`mobx` is a package that provides an abstraction over `React`'s state management. The three main concepts are:
+- `observable`: data stored in the component's `state`
+- `action`: a function that modifies any `observable` data
+- `computed`: data that is derived from `observable` data but is not actually stored. Think of this as computing `isEmpty` vs an `observable` field called `count`.
+
+Further reading is available from `mobx`'s [website](https://mobx.js.org/the-gist-of-mobx.html).
diff --git a/mkdocs.yml b/mkdocs.yml
index 993cb3496c..3e95eae065 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -33,6 +33,7 @@ nav:
       - Main Extension: extensions/guides/main-extension.md
       - Renderer Extension: extensions/guides/renderer-extension.md
       - Generator: extensions/guides/generator.md
+      - Working with mobx: extensions/guides/working-with-mobx.md
     - Testing and Publishing:
       - Testing Extensions: extensions/testing-and-publishing/testing.md
       - Publishing Extensions: extensions/testing-and-publishing/publishing.md