fixup! Document how to support different distributed worker backends

docs/src/support-preferences.md

@@ -7,29 +7,43 @@ that they are not compatible at all. E.g. you cannot
 you as a package developer want to make your package support both Distributed
 and DistributedNext, we suggest using
 [Preferences.jl](https://juliapackaging.github.io/Preferences.jl/stable/) to
-choose which library to load:
+choose which package to load.
+
+Here's an example for a package named Foo.jl:
 ```julia
-import Preferences: load_preference
+module Foo
+
+import Dependency
+import Preferences: @load_preference, @set_preferences!
 
-const distributed_library_name = load_preference("distributed-library", "name")
-if distributed_library_name == "DistributedNext"
+const distributed_package = @load_preference("distributed-package")
+if distributed_package == "DistributedNext"
     using DistributedNext
-elseif distributed_library_name == "Distributed"
+elseif distributed_package == "Distributed"
     using Distributed
 else
-    error("Unsupported `distributed-library`: '$(distributed_library_name)'")
+    error("Unsupported `distributed-package`: '$(distributed_package)'")
 end
-```
 
-`distributed-library` is a top-level name that we recommend all packages who
-want to support switching backends use. The advantage of using a global
-preference instead of a per-package preference is that you can set it once:
-```julia
-import Preferences: set_preferences!
+"""
+    set_distributed_package!(value[="Distributed|DistributedNext"])
 
-set_preferences!("distributed-library", "name" => "DistributedNext")
+Set a [preference](https://github.com/JuliaPackaging/Preferences.jl) for using
+either the Distributed.jl stdlib or DistributedNext.jl. You will need to restart
+Julia after setting a new preference.
+"""
+function set_distributed_package!(value)
+    # Set preferences for all dependencies
+    Dependency.set_distributed_package!(value)
+
+    @set_preferences!("distributed-package" => value)
+    @info "Foo.jl preference has been set, restart your Julia session for this change to take effect!"
+end
+
+end
 ```
 
-And all packages that support the `distributed-library` preference will pick
-that up automatically so an end-user doesn't need to worry about setting
-preferences for all of the dependencies of the package that they want to use.
+Users will then be able to call
+e.g. `Foo.set_distributed_package!("DistributedNext")`. Note that
+`Foo.set_distributed_package!()` should also set the preferences of any dependencies
+of Foo.jl that use a distributed worker package.