diff --git a/doc/docs.md b/doc/docs.md
index b98bfc3c22..5c1440b83d 100644
--- a/doc/docs.md
+++ b/doc/docs.md
@@ -5690,6 +5690,23 @@ pub mut:
 
 Function/method deprecations:
 
+Functions are deprecated before they are finally removed to give users time to migrate their code. 
+Adding a date is preferable in most cases. An immediate change, without a deprecation date, may be 
+used for functions that are found to be conceptually broken and obsoleted by much better 
+functionality. Other than that setting a date is advisable to grant users a grace period. 
+
+Deprecated functions cause warnings, which cause errors if built with `-prod`. To avoid immediate 
+CI breakage, it is advisable to set a future date, ahead of the date when the code is merged. This 
+gives people who actively developed V projects, the chance to see the deprecation notice at least 
+once and fix the uses. Setting a date in the next 30 days, assumes they would have compiled their 
+projects manually at least once, within that time. For small changes, this should be plenty time. 
+For complex changes, this time may need to be longer. 
+
+Different V projects and maintainers may reasonably choose different deprecation policies. 
+Depending on the type and impact of the change, you may want to consult with them first, before 
+deprecating a function.
+
+
 ```v
 // Calling this function will result in a deprecation warning