diff --git a/docs/reference/createPlugin-feature-flags.md b/docs/reference/createPlugin-feature-flags.md
index 6c3a5f0bc5..6da8d6b084 100644
--- a/docs/reference/createPlugin-feature-flags.md
+++ b/docs/reference/createPlugin-feature-flags.md
@@ -8,7 +8,25 @@ export type FeatureFlagsHooks = {
 };
 ```
 
-Then, later, if you want to check if the user has enabled them:
+## Using with useApi
+
+This is the **recommended** way of using the API. It's officially supported by Backstage. To use it, you'll first need to register the `FeatureFlags` API via `ApiRegistry` in your `apis.ts` in your App:
+
+```tsx
+import {
+  ApiHolder,
+  ApiRegistry,
+  featureFlagsApiRef,
+  FeatureFlags,
+} from '@backstage/core';
+
+const builder = ApiRegistry.builder();
+builder.add(featureFlagsApiRef, FeatureFlags);
+
+export default builder.build() as ApiHolder;
+```
+
+Then, later, you can directly use it via `useApi`:
 
 ```tsx
 import React, { FC } from 'react';
@@ -17,10 +35,27 @@ import { featureFlagsApiRef, useApi } from '@backstage/core';
 
 const ExampleButton: FC<{}> = () => {
   const featureFlagsApi = useApi(featureFlagsApiRef);
+  const handleClick = () => featureFlagsApi.enable('enable-example-feature');
 
-  const handleClick = () => {
-    featureFlagsApi.enable('enable-example-feature');
-  };
+  return (
+    <Button variant="contained" color="primary" onClick={handleClick}>
+      Enable the 'enable-example-feature' feature flag
+    </Button>
+  );
+};
+```
+
+## Using directly with the `FeatureFlags` object
+
+This is **only** for backwards-compatibility support for Spotify's internal Backstage plugins. This may be deprecated in the distant future so generally we advise against using it.
+
+```tsx
+import React, { FC } from 'react';
+import { Button } from '@material-ui/core';
+import { FeatureFlags } from '@backstage/core';
+
+const ExampleButton: FC<{}> = () => {
+  const handleClick = () => FeatureFlags.enable('enable-example-feature');
 
   return (
     <Button variant="contained" color="primary" onClick={handleClick}>
diff --git a/docs/reference/createPlugin.md b/docs/reference/createPlugin.md
index c0b4dece71..b19df50c22 100644
--- a/docs/reference/createPlugin.md
+++ b/docs/reference/createPlugin.md
@@ -32,8 +32,8 @@ import ExampleComponent from './components/ExampleComponent';
 
 export default createPlugin({
   id: 'new-plugin',
-  register({ router, featureFlags: { registerFeatureFlag } }) {
-    registerFeatureFlag('enable-example-component');
+  register({ router, featureFlags }) {
+    featureFlags.registerFeatureFlag('enable-example-component');
 
     router.registerRoute('/new-plugin', ExampleComponent);
   },