Add a note describing feature switches as last resort option (#11394)

Author: MichalStrehovsky

xml/System.Diagnostics.CodeAnalysis/FeatureSwitchDefinitionAttribute.xml

@@ -31,9 +31,15 @@
         corresponds to the feature switch specified by name.</para>
     </summary>
     <remarks>
-      <para>
-        IL rewriters and compilers can use this attribute to substitute the return value
-        of the specified property with the value of the feature switch.</para>
+      <format type="text/markdown"><![CDATA[
+IL rewriters and compilers can use this attribute to substitute the return value of the specified property with the value of the feature switch.
+
+The value of the feature switch can only be specified at the application level and affects the entire application. It is possible to get into situations where one library that is part of the application requires the feature switch to be turned on, but has no way to communicate this to the application author.
+
+Feature switches complicate unit testing and code sharing since different application configurations might have different values of the feature switch, and it's difficult to ensure all code paths work as expected.
+
+It is therefore preferable to structure APIs in a way that trimming can happen naturally without any feature switches. The use of feature switches should be reserved for situations where trimming needs to happen, but it's not feasible to change the APIs to allow trimming naturally.
+ ]]></format>
     </remarks>
     <example>
       <format type="text/markdown"><![CDATA[