Document Weeder usage

development.markdown

@@ -224,3 +224,15 @@ cabal run --enable-profiling unison-cli-main:exe:unison -- +RTS -p
 ## Native compilation
 
 See the [readme](scheme-libs/racket/unison/Readme.md).
+
+## Weeding
+
+The Nix devShell includes Weeder, a tool for detecting dead code.
+
+Before running it, make sure your build is up-to-date (`stack build --bench --no-run-benchmarks --test --no-run-tests --haddock`).
+
+Not building tests will result in false reports of dead code, because Weeder won’t see call sites of things used only by tests. However, if Weeder runs clean on the entire codebase, you can `stack clean && stack build && weeder` and the complaints Weeder emits will then be things that are defined in production code, but are only used in benchmarks, tests, or Haddock. This indicates either dead code that we’re testing, or test utilities that live in the wrong place. The former should be removed, and the later should be moved.
+
+Removing `root-instances` and then `weeder | grep --invert-match '\(Instance\)'` can show you types that are unused (but appear used because of the instances).
+
+__NB__: Sometimes weeder complains about HIE files being built with the wrong GHC version. To fix this, I’ve had success with deleting my .direnv cache. You can specify multiple directories for Weeder to search with `--hie-directory`, but can’t specify a directory to exclude.