Document behavior concerns regarding the full Rails stack [ci skip]

Related to a discussion on #15508

1 files changed, 24 insertions, 0 deletions

diff --git a/guides/source/api_documentation_guidelines.md b/guides/source/api_documentation_guidelines.md
index 2b6a9f61eb..5b95d925a1 100644
--- a/guides/source/api_documentation_guidelines.md
+++ b/guides/source/api_documentation_guidelines.md
@@ -330,4 +330,28 @@ A `:nodoc:` should never be added simply because a method or class is missing do
 
 To summarize, the Rails team uses `:nodoc:` to mark publicly visible methods and classes for internal use; changes to the visibility of API should be considered carefully and discussed over a pull request first.
 
+Regarding the Rails Stack
+-------------------------
+
+When documenting parts of Rails API, it's important to remember all of the
+pieces that go into the Rails stack.
+
+This means that behavior may change depending on the scope or context of the
+method or class you're trying to document.
+
+In various places there is different behavior when you take the entire stack
+into account, one such example is
+`ActionView::Helpers::AssetTagHelper.image_tag`:
+
+```ruby
+# image_tag("icon.png")
+#   # => <img alt="Icon" src="/assets/icon.png" />
+```
+
+Although the default behavior for `image_tag` is `/images/icon.png`, because
+the Rails stack includes Sprockets when using the Rails Asset Pipeline.
+
+In this case, we want to document the behavior of the _framework_, and not just
+this specific method.
+
 If you have a question on how the Rails team handles certain API, don't hesitate to open a ticket or send a patch to the [issue tracker](https://github.com/rails/rails/issues).