Good Package Documentation
is hard to write, really hard
If you have not read William Yao’s brilliant Reanimate: swearing at bad documentation from last month I wholeheartedly recommend it. In it William describes his own difficulties trying to understand the documentation of a remarkable and capable package. It will be an experience familiar to all Haskellers yet so little has been written about this. We need more of this.
Writing good package documentation is hard, really hard, but there seem to be particular pitfalls when it comes to writing good Haskell package documentation, which seem to be related to the relatively high levels of abstractions that Haskell package authors tend to favour.
Got an issue with any of this? Please share or drop me a line (see below).