diff --git a/docs/src/developers/conventions.md b/docs/src/developers/conventions.md
index 4bb1035b7b9..1e85584603c 100644
--- a/docs/src/developers/conventions.md
+++ b/docs/src/developers/conventions.md
@@ -35,3 +35,27 @@ get_attribute(c, MOI.ConstraintDualStart())
 set_attribute(c, MOI.ConstraintDualStart(), [2.0, -1.0, 1.0])
 dual_start_value(c)
 ```
+
+## `unset_` methods
+
+There are a variety of attributes in JuMP and MOI that can be "set" and "unset."
+For example, there is [`MOI.Silent`](@ref), and the corresponding
+[`set_silent`](@ref) and [`unset_silent`](@ref).
+
+Note how [`set_silent`](@ref) and [`unset_silent`](@ref) take a single argument
+(the model), where `set_silent(model)` corresponds to `MOI.set(model, MOI.Silent(), true)`
+and `unset_silent(model)` corresponds to `MOI.set(model, MOI.Silent(), false)`.
+We could have instead implemented a single method `set_silent(model, flag::Bool)`
+that corresponded to `MOI.set(model, MOI.Silent(), flag)`. Another example is
+[`unset_time_limit_sec`](@ref), which is equivalent to
+`set_time_limit_sec(model, nothing)`.
+
+We have come to regard the `unset_` design as a mistake, because it leads to a
+proliferation of unique function names instead of leveraging Julia's strength
+for multiple dispatch.
+
+The existing `unset_` names are retained for backwards compatibility, but, going
+forward, provide a single `set_` method and document what value type should be
+provided to restore the model to the default setting. Thus, we have
+[`set_string_names_on_creation`](@ref), but no corresponding
+`unset_string_names_on_creation`.