Here's what I came with chatting on irc: - haddock for documenting functions and types - the manual for everything else, including theory, developer introduction and resources, etc. This seems to be the status quo and working fine, until some possible future time when the manual becomes too full of code hacking advice.