Additional context
Haskell's development tooling has matured a lot in the last years. One of the important areas for improvement to me is documentation.

What is wrong with the docs?
Having recently switched from Stack back to Cabal i struggled with finding examples and explanations for parts of a .cabal file, typical use cases and wordings. I'm convinced that this has to do with the overall documentation structure. I propose to introduce a clear(er) division between tutorials, guides and reference and explanations as described in https://documentation.divio.com/ and to follow a structure similar to the documentation for Rust' package manager cargo: https://doc.rust-lang.org/cargo/index.html.

The issues i see

• Clear separation & explanation between Haskell projects, Haskell modules, Haskell components, Haskell/Cabal packages, Cabal file (internal) libraries and multi-package setup, (and "cradles" from HLS?) needed.
  • Define an official name for .cabal file, see A file that defines a Cabal package should be officially called «Cabal Pact». #8965 -> "package description" aka ".cabal file"
  • Define an official name for multi-package setup (in Rust they are called workspaces) -> "Cabal project"
  • [] Add context chapter to disambiguate these packaging terms, e.g. using this structure.
• Move Nix related phrasing and usage examples to one or few separate guides chapters (beginners and average Haskellers probably don't know or care about NixOS).
• Move Setup.hs to separate (legacy?) chapter.
• Separate guides (how to a typical task during development) from reference (look up how syntax and flags of parts of Cabal and .cabal files)
  • Ensure every guide has it's own web page (easier to find through search indexes).
  • Introduce top-level "Guides" and "Reference" sections. Remove or rename existing reference section to e.g. "keyword-reference" -> Restructure user guide into top-level guides, reference and explanation parts #9379
  • Split existing content into guide and reference chapters. -> Restructure user guide into top-level guides, reference and explanation parts #9379
  • Write guide how to setup a (monorepo) project with multiple internal libraries and executables.
  • Write guide how and when to setup a monorepo as a multi-package project. (including https://discourse.haskell.org/t/monorepo-cabal-internal-libraries-vs-multi-package-cabal/7424/4)
  • Write guide to create self-contained/statically linked binaries.
  • Write guide how to cross-compile GHC and projects to ARM/aarch64, RISC-V,GHCjs, wasm?
  • Write guide how to speed up build for dev and prod. E.g. how does cabal parallalization -j act with GHC parallalization.
  • Write guide how to setup and run tests, e.g. run a specific test, run tests matching filters, auto-run (subset of) tests on changes.
  • Write guide to benchmark/profile Haskell code (similar to https://www.youtube.com/watch?v=nIyaC3JtlyQ ?) with links on how to improve performance -> Add a performance measuring top-level user guide page #10539
  • Write guide page how to use non-Hackage dependencies like raw Git repositories. -> Thanks to @philderbeast for source-repository versus source-repository-package #9701
• Create a compact and beginner-friendly introduction chapter
• Create a more compact and beginner-friendly Getting-Started chapter.
  • See a first improvement Restructure Getting Started documentation to be more compact and beginner friendly #9212
• Ensure consistent use of placeholder syntax, e.g. .cabal
• Add more examples on version constraints and links to PVP reference.
• Add section or guide how to represent optional dependencies through separate packages with orphan instances as in https://discourse.haskell.org/t/how-to-give-libraries-optional-dependencies/9752

If you also see the need to improve the documentation (and what and what else to do first and how), feedback is welcome. I started with a small improvement in #9212.