diff --git a/ui/components/README.md b/ui/components/README.md
index 85dddb820..313c65a8d 100644
--- a/ui/components/README.md
+++ b/ui/components/README.md
@@ -1 +1,13 @@
-# Componnet Control Editors
+# @component-controls/components
+
+> Component controls user interface components
+
+## Installation
+
+This package is usually installed as part of the @component-controls package, but you can also install it standalone
+
+```bash
+$ npm install @component-controls/components --save-dev
+```
+
+# Components
\ No newline at end of file
diff --git a/ui/components/src/Markdown/Markdown.tsx b/ui/components/src/Markdown/Markdown.tsx
index 10d435df8..16764999d 100644
--- a/ui/components/src/Markdown/Markdown.tsx
+++ b/ui/components/src/Markdown/Markdown.tsx
@@ -4,7 +4,13 @@ import MarkdownToJSX, { MarkdownOptions } from 'markdown-to-jsx';
 import { SyntaxHighlighter } from '../SyntaxHighlighter';
 
 export interface MarkdownProps {
+  /**
+   * the markdown code is passed as a children prop
+   */
   children: string;
+  /**
+   * components to customize the markdown display
+   */
   components?: MarkdownOptions['overrides'];
 }
 
diff --git a/ui/components/src/Popover/Popover.tsx b/ui/components/src/Popover/Popover.tsx
index 10e6162a2..7fa0279cb 100644
--- a/ui/components/src/Popover/Popover.tsx
+++ b/ui/components/src/Popover/Popover.tsx
@@ -80,6 +80,11 @@ export const Arrow = styled.div<{ placement: string; borderColor: string }>(
   }),
 );
 
+/**
+ * A Popover container that is triggered by a click, or hover
+ * used to display enhanced information that could not fit into the main scren
+ *
+ */
 export const Popover: FC<PopoverProps> = ({
   trigger,
   placement = 'bottom',