Provide more details for marking APIs as preview

Author: Immo Landwerth

xml/System.Diagnostics.CodeAnalysis/ExperimentalAttribute.xml

@@ -30,7 +30,13 @@
   </Attributes>
   <Docs>
     <summary>Indicates that an API is experimental and it may change in the future.</summary>
-    <remarks>This attribute allows call sites to be flagged with a diagnostic that indicates that an experimental feature is used. Authors can use this attribute to ship preview features in their assemblies.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+<xref:System.Diagnostics.CodeAnalysis.ExperimentalAttribute> allows call sites to be flagged with a diagnostic that indicates that an experimental feature is used. You can use this attribute to ship preview features in otherwise stable libraries.
+
+For more information about using how APIs can be marked as preview, see [Attributes](dotnet/fundamentals/apicompat/preview-apis).
+      ]]></format>
+    </remarks>
     <seealso cref="T:System.Runtime.Versioning.RequiresPreviewFeaturesAttribute" />
   </Docs>
   <Members>

xml/System.Runtime.Versioning/RequiresPreviewFeaturesAttribute.xml

@@ -32,7 +32,15 @@
   </Attributes>
   <Docs>
     <summary>Indicates that an API is in preview. This attribute allows call sites to be flagged with a diagnostic that indicates that a preview feature is used. Authors can use this attribute to ship preview features in their assemblies.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[
+<xref:System.Runtime.Versioning.RequiresPreviewFeaturesAttribute> marks an API as requiring preview functionality from the .NET runtime, its core libraries, and the compilers. This API generally shouldn't be used by your code and is instead reserved for platform provided functionality.
+
+If you want to ship preview functionality in your own libraries, you should use <xref:System.Diagnostics.CodeAnalysis.ExperimentalAttribute>.
+
+For more information about using how APIs can be marked as preview, see [Attributes](dotnet/fundamentals/apicompat/preview-apis).
+      ]]></format>
+    </remarks>
     <related type="Article" href="https://aka.ms/dotnet-warnings/preview-features">Preview Features</related>
   </Docs>
   <Members>