diff --git a/docs/extensions/guides/catalog.md b/docs/extensions/guides/catalog.md
index 0056bca1ec..843aaf4f44 100644
--- a/docs/extensions/guides/catalog.md
+++ b/docs/extensions/guides/catalog.md
@@ -4,42 +4,82 @@ When developing an extension you can program your entities to be represented in
 
 In catalog view catalog entities are grouped by catalog categories. Each category needs to be registered with an observable source
 
-
 ## CatalogCategoryRegistry
 `CatalogCategoryRegistry` keeps track of all entity categories registered with Lens. It is a singleton object that could be imported from extensions API:
-```typescript
-import { Main, Common } from "@k8slens/extensions";
-
-class CatalogCategory extends Common.Catalog.CatalogCategory {
-  public readonly apiVersion = "catalog.k8slens.dev/v1alpha1";
-  public readonly kind = "CatalogCategory";
-  public metadata = {
-    name: "Spaces",
-    icon: "scatter_plot"
-  };
-  public spec: Common.Catalog.CatalogCategorySpec = {
-    group: "entity.k8slens.dev",
-    versions: [
-      {
-        name: "v1alpha1",
-        entityClass: SpaceCatalogEntity
-      }
-    ],
-    names: {
-      kind: spaceCatalogEntityKind
-    }
-  };
-}
-
-const spaceCatalog = new CatalogCategory();
-
-Main.Catalog.catalogCategories.add(spaceCatalog);
-```
 
 1. Create an entity
+First, you'll have to create an entity by extending a `CatalogEntity` class. You can provide your own types for entity metadata, status info and specification.
+  ```typescript
+  import { Common } from "@k8slens/extensions";
+
+  export const Kind = "MyEntity";
+
+  export class MyCatalogEntity extends Common.Catalog.CatalogEntity<
+    Common.Catalog.CatalogEntityMetadata,
+    CatalogEntityStatus
+  > {
+    public readonly apiVersion = "entity.k8slens.dev/v1alpha1";
+    public readonly kind = Kind;
+
+    async onRun(ctx: Common.Catalog.CatalogEntityActionContext) {
+      // Is called once the user interacts with the entity, e.g. clicks on a hotbar item
+    }
+
+    onDetailsOpen(): void {
+      // Is called when the user launches detailed view of the entity
+    }
+
+    onSettingsOpen(): void {
+      // Is called when the user launches settings view of the entity
+    }
+
+    onContextMenuOpen(): void {
+      // Is called when the user opens the context menu for the entity
+    }
+  }
+  ```
 1. Create an entity category
-1. Register an entity with `CatalogCategoryRegistry`
-1. Add catalog source
+  ```typescript
+  import { Main, Common } from "@k8slens/extensions";
+  import { MyCatalogEntity, Kind } from ".";
+
+  class CatalogCategory extends Common.Catalog.CatalogCategory {
+    public readonly apiVersion = "catalog.k8slens.dev/v1alpha1";
+    public readonly kind = "CatalogCategory";
+    public metadata = {
+      name: "My Entities",
+      icon: "scatter_plot"
+    };
+    public spec: Common.Catalog.CatalogCategorySpec = {
+      group: "entity.k8slens.dev",
+      versions: [
+        {
+          name: "v1alpha1",
+          entityClass: MyCatalogEntity
+        }
+      ],
+      names: {
+        kind: Kind
+      }
+    };
+  }
+  ```
+
+1. Register an entity with `CatalogCategoryRegistry` and add a source
+
+```typescript
+export default class LensCloudExtensionMain extends Main.LensExtension {
+  // ...
+  private myCatalog = new CatalogCategory();
+  private myEntitySource: IObservableArray<MyCatalogEntity>;
+
+  async onActivate() {
+    Main.Catalog.catalogCategories.add(this.myCatalog);
+    this.addCatalogSource("spaceCatalogEntiesSource", this.myEntitySource);
+    // ...
+  }
+}
+```
 
 ## CatalogEntityRegistry
 Provides access to current active catalog entity, as well as a function `getItemsForApiKind()`for aggregating registered entities by group and kind.
\ No newline at end of file