diff --git a/plugins/pagerduty/README.md b/plugins/pagerduty/README.md
index 0335cb5a9b..9c5c0b2485 100644
--- a/plugins/pagerduty/README.md
+++ b/plugins/pagerduty/README.md
@@ -1,13 +1,89 @@
-# pagerduty
+# PagerDuty
 
-Welcome to the pagerduty plugin!
+## Overview
 
-_This plugin was created through the Backstage CLI_
+This plugin displays PagerDuty information about an entity such as if there are any active incidents and how the escalation policy looks like.
 
-## Getting started
+There is also an easy way to trigger an alarm directly to the person who is currently on-call.
 
-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 [/pagerduty](http://localhost:3000/pagerduty).
+This plugin requires that entities are annotated with an [integration key](https://support.pagerduty.com/docs/services-and-integrations#add-integrations-to-an-existing-service). See more further down in this document.
 
-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.
+This plugin provides:
+
+- A list of incidents
+- A way to trigger an alarm to the person on-call
+- Information details about the person on-call
+
+## Setup instructions
+
+Install the plugin:
+
+```bash
+yarn add @backstage/plugin-pagerduty
+```
+
+Add it to the app in `plugins.ts`:
+
+```ts
+export { plugin as Pagerduty } from '@backstage/plugin-pagerduty';
+```
+
+Add it to the `EntityPage.ts`:
+
+```ts
+import {
+  isPluginApplicableToEntity as isPagerDutyAvailable,
+  PagerDutyCard,
+} from '@backstage/plugin-pagerduty';
+// add to code
+{
+  isPagerDutyAvailable(entity) && (
+    <Grid item md={6}>
+      <PagerDutyCard entity={entity} />
+    </Grid>
+  );
+}
+```
+
+## Client configuration
+
+The PagerDutyClient can be configured with the appropriate urls:
+
+In `apis.ts`:
+
+```ts
+createApiFactory({
+  api: pagerDutyApiRef,
+  deps: { configApi: configApiRef },
+  factory: ({ configApi }) =>
+    new PagerDutyClientApi({
+      api_url: `https://api.pagerduty.com`,
+      events_url: 'https://events.pagerduty.com/v2',
+  }),
+}),
+```
+
+## Providing the API Token
+
+In order for the client to make requests to the [PagerDuty API](https://developer.pagerduty.com/docs/rest-api-v2/rest-api/) it needs an [API Token](https://support.pagerduty.com/docs/generating-api-keys#generating-a-general-access-rest-api-key).
+
+Then start the backend passing the token as an environment variable:
+
+```bash
+$ PAGERDUTY_TOKEN='Token token=<TOKEN>' yarn start
+```
+
+This will proxy the request by adding `Authorization` header with the provided token.
+
+## Integration Key
+
+The information displayed for each entity is based on the [integration key](https://support.pagerduty.com/docs/services-and-integrations#add-integrations-to-an-existing-service).
+
+### Adding the integration key to the entity annotation
+
+If you want to use this plugin for an entity, you need to label it with the below annotation:
+
+```yml
+annotations:
+  pagerduty.com/integration-key: [INTEGRATION_KEY]
+```