What packages need better documentation the most?

1

In How to grow the (commercial) Haskell user base? - #62 by malteneuss a lot of comments hinted at better documentation to help with Haskell adoption. I’m wondering what packages/tools would benefit the most from improved documentation? Such package should best be widely useful, popular and usable for Haskell beginners (e.g. coming from another programming language). Maybe people can get together and improve documentation afterwards.

For me it’s the following packages:

  • Cabal: everyone must use or at least understand the main package manager… the doc structure was already improved recently; needs a few more guides, see https://github.com/haskell/cabal/issues/9214)
  • Yesod: Popular, pragmatic, down-to-earth web framework without type-level magic. Template Haskell generates much “magic” though under the hood that you need to understand as soon as you deviate from examples, and the Yesod book should become atomic, isolated guide pages.
  • Persistent Popular, pragmatic Nosql/Sql Database framework. Again much Template Haskell difficult to grasp code generation that you have to understand, but isn’t documented well; at least hard to discover).
3 Likes
2

template-haskell itself is probably the package where the severity of the documentation gap multiplied by the number of times I’ve been impeded by it is highest.

4 Likes
3

a brief tutorial section for the most common (easy too?) uses of th, would also be appreciated. I did not understand at all how to use the package from its docs, and reading the paper (which afaik is outdated) is a total blocker to most people imo