diff --git a/app/models/concerns/participable.rb b/app/models/concerns/participable.rb
index a01b28ea8db..7a5e4876ff2 100644
--- a/app/models/concerns/participable.rb
+++ b/app/models/concerns/participable.rb
@@ -1,3 +1,27 @@
+# == Participable concern
+#
+# Contains functionality related to objects that can have participants, such as
+# an author, an assignee and people mentioned in its description or comments.
+#
+# Used by Issue, Note, MergeRequest, Snippet and Commit.
+#
+# Usage:
+#
+#     class Issue < ActiveRecord::Base
+#       include Participable
+#
+#       # ...
+#
+#       participant :author, :assignee, :mentioned_users, :notes
+#     end
+#     
+#     issue = Issue.last
+#     users = issue.participants
+#     # `users` will contain the issue's author, its assignee,
+#     # all users returned by its #mentioned_users method,
+#     # as well as all participants to all of the issue's notes,
+#     # since Note implements Participable as well.
+#
 module Participable
   extend ActiveSupport::Concern