diff --git a/plugins/github-issues/README.md b/plugins/github-issues/README.md
index 65757bef00..eeb93ab27b 100644
--- a/plugins/github-issues/README.md
+++ b/plugins/github-issues/README.md
@@ -1,13 +1,63 @@
-# github-issues
+# GitHub Issues plugin
 
-Welcome to the github-issues plugin!
+Welcome to the GitHub Issues plugin!
 
-_This plugin was created through the Backstage CLI_
+Based on the [well-known GitHub slug annotation](https://backstage.io/docs/features/software-catalog/well-known-annotations#githubcomproject-slug) associated with the Entity, it renders the list of Open issues in GitHub.
 
-## Getting started
+The plugin is designed to work with four Entity kinds, and it behaves a bit differently depending on that kind:
 
-Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn start` in the root directory, and then navigating to [/github-issues](http://localhost:3000/github-issues).
+- Kind: Group/User: plugin renders issues from all repositories for which the Entity is the owner.
+- Kind: API/Component: plugin renders issues from only one repository assigned to the Entity
 
-You can also serve the plugin in isolation by running `yarn start` in the plugin directory.
-This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads.
-It is only meant for local development, and the setup for it can be found inside the [/dev](./dev) directory.
+**Issues are sorted from the recently updated DESC order (the plugin might not render all issues from a single repo next to each other).**
+
+## Prerequisites
+
+- [GitHub Authentication Provider](https://backstage.io/docs/auth/github/provider)
+
+## Usage
+
+Install the plugin by running the following command **from your Backstage root directory**
+
+`yarn --cwd packages/app add @backstage/plugin-github-issues`
+
+After installation, the plugin can be used as a Card or as a Page.
+
+```typescript
+import {
+  GitHubIssuesCard,
+  GitHubIssuesPage,
+} from '@backstage/plugin-github-issues';
+
+// To use as a page Plugin needs to be wrapped in EntityLayout.Route
+const RenderGitHubIssuesPage = () => (
+  <EntityLayoutWrapper>
+    <EntityLayout.Route path="/" title="Overview">
+      <EntityLayout.Route path="github-issues" title="GitHub Issues">
+        <GitHubIssuesPage />
+      </EntityLayout.Route>
+    <EntityLayout.Route />
+  </EntityLayoutWrapper>
+);
+
+// To use as a card and make it render correctly please place it inside appropriate Grid elements
+const RenderGitHubIssuesCard = () => (
+  <EntityLayoutWrapper>
+    <EntityLayout.Route path="/" title="Overview">
+      <Grid container spacing={3}>
+        <Grid item xs={12}>
+          <GitHubIssuesCard />
+        </Grid>
+      </Grid>
+    <EntityLayout.Route />
+  </EntityLayoutWrapper>
+);
+```
+
+## Configuration
+
+Both `GitHubIssuesPage` and `GitHubIssuesCard` provide default configuration. It is ready to use out of the box.
+However, you can configure the plugin with props:
+
+- `itemsPerPage: number = 10` - Issues in the list are paginated, number of issues on a single page is controlled with this prop
+- `itemsPerRepo: number = 40` - the plugin doesn't download all Issues available on GitHub. By default, it will get at most 40 Issues - this prop controls this behaviour