Devs, I have some important information for everyone. TL;DR1 As a rule of thumb, whenever you modify DynFlags or StaticFlags please make absolutely sure that your changes are described in the User's Guide. See Note [Updating flag description in the User's Guide] in DynFlags. TL;DR2 Your help is needed to update the User's Guide. I've spent last two days on updating the flag descriptions in the User's Guide (#9358). Saying that things were a complete mess would be an understatement. We had lots of flags that were not documented in the user's guide, we had documentation for flags that no longer exist, lots of flags were incorrectly labeled as static, etc. It seems that we don't have a habit of updating User's Guide when we change the code responsible for flags. I updated huge chunks of the documentation and things are in a better shape now. But if we forget to update documentation when we make changes then in 2 or 3 years things will most likely be as bad as they were before my clean-up. I added a Note and lots of references to it to remind us about that. If things go well we might even have a Herald rule to remind about updating User's Guide whenever DynFlags and StaticFlags are modified by a commit/revision [1]. However, the task of updating flag descriptions in the User's Guide is not finished. My main focus were the -f*/-fno-* optimisation flags described primarily in sections 4.10 and 4.19.15 (note that HEAD has different section numbers than 7.8.3). I updated what I could but there are still some descriptions missing - I'm not familiar with some of flags that we have. Here's where your help is required. These flags are currently completely missing from the User's Guide: -fbuilding-cabal-package -fflat-cache -fhpc-no-auto -fkill-absence -fkill-one-shot -fsimple-list-literals -fspecialise-aggressively -fuse-rpaths -fspec-constr-recursive -ffloat-lam-args -ffloat-all-lams If you can provide description for any of these flags please edit flags.xml and using.xml. I suspect that -fkill-absence might be related to demand analysis - CCing Nicolas Frisby. Following flags are listed in Flag Reference section (4.19) with a brief one sentence description but they don't have a detailed description in section 4.10 (using.xml): -fcall-arity (CCing Joachim) -funfolding-fun-discount -funfolding-dict-discount -funfolding-keeness-factor -frule-check (see #9776) Following flags have a detailed description but it is confusing: -fdo-eta-reduction -fdo-lambda-eta-expansion Follwoing flags have a description but it is too brief. We should have more details: -fdicts-cheap -fdicts-strict -fdmd-tx-dict-sel (Nicolas, can you update that?) -fmax-inline-memcpy-insns -fmax-inline-memset-insns -fmax-worker-args -fno-opt-coercion -fno-pre-inlining -fsimplifier-phases -fspec-constr-threshold -fspec-constr-count -fstrictness-before These flags were deliberately omitted from the User's Guide because they are deprectaed and will be removed: -fext-core -frewrite-rules For these flags Flag Reference section provides the description of their -fno-* version: -fembed-manifest -fgen-manifest -fghci-history -fghci-sandbox -fpre-inlining -fprint-bind-contents -fprof-count-entries -fshared-implib This seems to go against our convention of describing the flags. Should we revert to desribing their normal version (ie. ones that enable something, not disable)? As part of my work I also removed -ddump-core-pipeline and -ddump-simpl-phases, which weren;t very useful. And I cleaned up DynFlags by putting some of the long lists of flags into alphabetical order. This change is a bit invasive - I'm sorry if it causes merge conflicts, but I believe that in the long run this is beneficial. As I already said I focused primarily on -f* flags. But we should also make sure that documentation of remaining flags is up to date, especially the -d* ones. I don't have more time to put into this so I'm asking for a collective effort to update the User's Guide, especially that we are moving closer to 7.10 release. Janek [1] https://phabricator.haskell.org/T52