diff --git a/src/core/server/deprecations/README.mdx b/src/core/server/deprecations/README.mdx
index 6ba051e86f4ead..e97fe27bcaac5f 100644
--- a/src/core/server/deprecations/README.mdx
+++ b/src/core/server/deprecations/README.mdx
@@ -22,10 +22,9 @@ To check your plugin deprecations go to the UA interface and click on `view depr
 ## How do I use this service for deprecated plugin configurations?
 The deprecations service automatically hooks deprecated configs with the deprecations service. 
 
-All the config deprecation functions (`unused`, `unusedFromRoot`, `rename`, `renameFromRoot`) now accept an optional parameter to customize the deprecation details.
+All the config deprecation functions (`unused`, `unusedFromRoot`, `rename`, `renameFromRoot`) accept an optional parameter to customize the deprecation details.
 
 ### Example
-
 ```ts
 export const config: PluginConfigDescriptor<ConfigType> = {
   schema: configSchema,
@@ -42,15 +41,16 @@ The service will show the following details about the deprecation:
 
 ```ts
 {
-  "deprecationsInfo":[{
-    "level":"critical",
-    "message": "\"ui_metric.debug\" is deprecated and has been replaced by \"usageCollection.uiCounters.debug\"",
-    "documentationUrl": 'elastic.co/some-url',
-    "correctiveActions":{
-      "manualSteps": [
+  deprecationsInfo:[{
+    level: 'critical',
+    message: `"ui_metric.debug" is deprecated and has been replaced by "usageCollection.uiCounters.debug"`,
+    documentationUrl: 'elastic.co/some-url',
+    correctiveActions:{
+      manualSteps: [
         `Replace "ui_metric.debug" with "usageCollection.uiCounters.debug" in the Kibana config file, CLI flag, or environment variable (in Docker only).`,
-      },
-    "domainId":"usageCollection",
+      ]
+    },
+    domainId: 'usageCollection',
   }],
 }
 ```
@@ -58,7 +58,7 @@ The service will show the following details about the deprecation:
 #### Custom deprecations for plugin configs
 Custom config deprecation handling allows specifying the deprecation details via the `addDeprecation`.
 
-##### Example:
+##### Example
 
 ```ts
 export const config: PluginConfigDescriptor<ConfigSchema> = {
@@ -94,39 +94,27 @@ export const config: PluginConfigDescriptor<ConfigSchema> = {
 };
 ```
 
-## How do I use this service for my deprecated plugin features?
+## How do I add deprecations for non-config plugin deprecations?
+
 Plugins are responsible for registering any deprecations during the `setup` lifecycle by using the deprecations service.
 
+Examples of non-config deprecations include things like
+- timelion sheets
+- kibana_user security roles 
+
+This service is not intended to be used for non-user facing deprecations or cases where the deprecation cannot be 'detected' by this mechanism.
+
+### Usage
 ```ts
 coreSetup.deprecations.registerDeprecations({
   getDeprecations: ({ esClient, savedObjectsClient }) => [{ ...`<list of deprecations>` }],
 });
 ```
 
-The `getDeprecations` function is invoked when the user requests to see the deprecations affecting their deployment. The function is passed a context object `{ esClient, savedObjectsClient }`.
-
-```ts
-interface GetDeprecationsContext {
-  esClient: IScopedClusterClient;
-  savedObjectsClient: SavedObjectsClientContract;
-}
+The `getDeprecations` function is invoked when the user requests to see the deprecations affecting their deployment.
+The function provides a context object which contains a scoped elasticsearch client and a saved objects client.
 
-interface DeprecationInfo {
-  message: string;
-  level: 'warning' | 'critical';
-  documentationUrl?: string;
-  correctiveActions: {
-    api?: {
-      path: string;
-      method: 'POST' | 'PUT';
-      body?: {
-        [key: string]: any;
-      };
-    };
-    manualSteps?: string[];
-  }; 
-}
-```
+To check the full TS types of the service please check the [generated core docs](../../../../docs/development/core/server/kibana-plugin-core-server.deprecationsservicesetup.md).
 
 ### Example
 ```ts
@@ -138,29 +126,29 @@ async function getDeprecations({ esClient, savedObjectsClient }: GetDeprecations
 
   if (testDashboardUser) {
   deprecations.push({
-    "message": "User 'test_dashboard_user' is using a deprecated role: 'kibana_user'",
-    "documentationUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-user.html",
-    "level": "critical",
-    "correctiveActions": {
-      "api": {
-          "path": "/internal/security/users/test_dashboard_user",
-          "method": "POST",
-          "body": {
-            "username": "test_dashboard_user",
-            "roles": [
-              "machine_learning_user",
-              "enrich_user",
-              "kibana_admin"
+    message: 'User "test_dashboard_user" is using a deprecated role: "kibana_user"',
+    documentationUrl: 'https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-user.html',
+    level: 'critical',
+    correctiveActions: {
+      api: {
+          path: '/internal/security/users/test_dashboard_user',
+          method: 'POST',
+          body: {
+            username: 'test_dashboard_user',
+            roles: [
+              'machine_learning_user',
+              'enrich_user',
+              'kibana_admin'
             ],
-            "full_name": "Alison Goryachev",
-            "email": "alisongoryachev@gmail.com",
-            "metadata": {},
-            "enabled": true
+            full_name: 'Alison Goryachev',
+            email: 'alisongoryachev@gmail.com',
+            metadata: {},
+            enabled: true
           }
       },
-      "manualSteps": [
-        "Using Kibana user management, change all users using the kibana_user role to the kibana_admin role.",
-        "Using Kibana role-mapping management, change all role-mappings which assing the kibana_user role to the kibana_admin role."
+      manualSteps: [
+        'Using Kibana user management, change all users using the kibana_user role to the kibana_admin role.',
+        'Using Kibana role-mapping management, change all role-mappings which assing the kibana_user role to the kibana_admin role.'
       ]
     },
   });
@@ -184,7 +172,7 @@ To check the deprecation in the UI pleae check the UA page.
 
 To test that your logic registering the deprecations with the deprecations service during `setup` is valid we recommend adding unit tests to check that the `getDeprecations` is returning the expected array of deprecations at different scenarios.
 
-Core provides `mocks` for the service which should help you focus on testing only your specific requirements.
+Core provides mocks for the service which should help you focus on testing only your specific requirements.
 
 You can also use the deprecations service API; The deprecations service exposes an api `GET /api/deprecations/` which provides a list of deprecations and possible corrective actions required to resolve these entries. The context is scoped to the requesting user, hence a user with limited access might not be able to see all the deprecations affecting the deployment.