Encourage dynamic dispatch as a default

README.md

@@ -161,7 +161,8 @@ The library is split among several packages:
 For the examples see the *Introduction* sections of
 [`Effectful.Dispatch.Dynamic`](https://hackage.haskell.org/package/effectful-core/docs/Effectful-Dispatch-Dynamic.html)
 and
-[`Effectful.Dispatch.Static`](https://hackage.haskell.org/package/effectful-core/docs/Effectful-Dispatch-Static.html).
+[`Effectful.Dispatch.Static`](https://hackage.haskell.org/package/effectful-core/docs/Effectful-Dispatch-Static.html)
+(when in doubt, start with dynamic dispatch).
 
 ## Acknowledgements
 

effectful-core/src/Effectful.hs

@@ -97,7 +97,8 @@ import Effectful.Internal.Monad
 --
 -- It implements support for extensible effects with both dynamic and static
 -- dispatch. For more information about each type consult the documentation in
--- "Effectful.Dispatch.Dynamic" and "Effectful.Dispatch.Static".
+-- "Effectful.Dispatch.Dynamic" and "Effectful.Dispatch.Static" (when in doubt,
+-- start with dynamic dispatch).
 --
 -- The library provides:
 --
@@ -109,7 +110,8 @@ import Effectful.Internal.Monad
 --   t'Effectful.Writer.Static.Local.Writer'.
 --
 -- - Utilities for defining new effects and interpreting them, possibly in terms
---   of already existing ones.
+--   of already existing ones (see introduction of the
+--   "Effectful.Dispatch.Dynamic" module for more information).
 --
 -- While basic effects can be used out of the box, in general it's recommended
 -- to create your own that serve a more specific purpose.

effectful-core/src/Effectful/Dispatch/Static.hs

@@ -57,9 +57,7 @@ import Effectful.Internal.Monad
 -- * If the effect you're about to define has only one reasonable
 --   implementation, it makes a lot of sense to make it statically dispatched.
 --
--- Statically dispatched effects also perform slightly better than dynamically
--- dispatched ones, because their operations are implemented as standard top
--- level functions, so the compiler can apply more optimizations to them.
+-- __When in doubt, use dynamic dispatch as it's more flexible.__
 --
 
 -- $example