diff --git a/pkg/analysis_server/lib/src/services/completion/yaml/analysis_options_generator.dart b/pkg/analysis_server/lib/src/services/completion/yaml/analysis_options_generator.dart
index b362aa4bc5b..62d845a3a35 100644
--- a/pkg/analysis_server/lib/src/services/completion/yaml/analysis_options_generator.dart
+++ b/pkg/analysis_server/lib/src/services/completion/yaml/analysis_options_generator.dart
@@ -106,7 +106,7 @@ class _LintRuleProducer extends Producer {
     for (var rule in Registry.ruleRegistry.rules) {
       // TODO(pq): consider suggesting internal lints if editing an SDK options file
       if (!rule.state.isInternal) {
-        yield identifier(rule.name, docComplete: rule.details);
+        yield identifier(rule.name, docComplete: rule.description);
       }
     }
   }
diff --git a/pkg/analysis_server/test/src/services/completion/yaml/analysis_options_generator_test.dart b/pkg/analysis_server/test/src/services/completion/yaml/analysis_options_generator_test.dart
index ca4782c5d9a..a0d3f2bdbfd 100644
--- a/pkg/analysis_server/test/src/services/completion/yaml/analysis_options_generator_test.dart
+++ b/pkg/analysis_server/test/src/services/completion/yaml/analysis_options_generator_test.dart
@@ -150,7 +150,7 @@ linter:
     var completion = assertSuggestion('annotate_overrides');
     expect(
       completion.docComplete,
-      contains('**DO** annotate overridden methods and fields'),
+      contains('Annotate overridden members.'),
     );
   }
 
diff --git a/pkg/analyzer/lib/src/lint/linter.dart b/pkg/analyzer/lib/src/lint/linter.dart
index 514a51fde7c..ac847e41651 100644
--- a/pkg/analyzer/lib/src/lint/linter.dart
+++ b/pkg/analyzer/lib/src/lint/linter.dart
@@ -195,6 +195,10 @@ abstract class LintRule {
 
   /// Description (in markdown format) suitable for display in a detailed lint
   /// description.
+  ///
+  /// This property is deprecated and will be removed in a future release.
+  @Deprecated('Use .description for a short description and consider placing '
+      'long-form documentation on an external website.')
   final String details;
 
   /// Short description suitable for display in console output.
@@ -213,7 +217,7 @@ abstract class LintRule {
     required this.name,
     this.categories = const <String>{},
     required this.description,
-    required this.details,
+    this.details = '',
     State? state,
   }) : state = state ?? State.stable();
 
diff --git a/pkg/linter/test/validate_rule_description_format_test.dart b/pkg/linter/test/validate_rule_description_format_test.dart
index 2d24d48d718..20027f42bd4 100644
--- a/pkg/linter/test/validate_rule_description_format_test.dart
+++ b/pkg/linter/test/validate_rule_description_format_test.dart
@@ -2,6 +2,8 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
+// ignore_for_file: deprecated_member_use
+
 import 'package:analyzer/src/lint/registry.dart';
 import 'package:test/test.dart';
 
diff --git a/pkg/linter/tool/machine.dart b/pkg/linter/tool/machine.dart
index 9e20cf58cf7..d30e6f31ab6 100644
--- a/pkg/linter/tool/machine.dart
+++ b/pkg/linter/tool/machine.dart
@@ -85,6 +85,7 @@ Future<String> getMachineListing(
         ],
         'fixStatus':
             fixStatusMap[rule.lintCodes.first.uniqueName] ?? 'unregistered',
+        // ignore: deprecated_member_use
         'details': rule.details,
         if (sinceInfo != null)
           'sinceDartSdk': sinceInfo[rule.name]?.sinceDartSdk ?? 'Unreleased',