I meant to post this about 30 minutes ago, but I accidentally sent it only to Michael Snoyman. It seems to me that there are two use cases here - documentation inside code and documentation that stands alone. I agree with you, Michael, that there is no reason why you shouldn't be able to use whichever documentation method you prefer in your readme file. Since it stands alone, it should be trivial to include support for a multitude of formats and display the resulting documentation on Hackage. I think where Mateusz' opinion differs is on the inclusion of markdown in source files (correct me if I am wrong):

More importantly, Markdown is not suited for documenting code. We'd have to introduce new identifiers if we wanted to link to some functions from our synopsis. 16th standard aside, this is quickly starts looking like Haddock.

As he says, there are problems with using markdown this way. I think it would be beneficial to have a defacto standard for documentation that lives inside source files - this would prevent it from changing from file to file and provide consistency across the community's code-base. Because the haskell community controls haddock it is in a better position to evolve to our needs. Some flavor of markdown that has a user-base outside the haskell community may not be willing to incorporate changes that make it a better fit for living inside haskell source files, so we would have to maintain our own fork of it anyway. Why duplicate the work that has already been done? I think if the community has a problem with haddock syntax that can be discussed and, if need be, changed. But I do believe that there should be consistency in source file documentation. The last problem I see is the cabal problem. It seems that cabal has trouble handling edge cases, and I think that is again something we can work on (I may even look into it myself - I have been looking for a project). It seems like it would be a good idea to only include small blurbs about the project in the .cabal file, and to separate the larger documentation into a README file, like is done on github. The reasoning behind this is two-fold: 1) Cabal files are human readable. They give us insight into the dependencies a project requires, and including full documentation here would make it harder to get a quick overview of the project (I know most people use hackage for this, but cabal was chosen over formats like XML specifically because it was meant to be read and understood by humans). 2) Separating the README file allows users to choose their favorite format, and be certain that it will be formatted as it was intended (cabal can't be expected to handle every edge case of every format - there are far too many, and Pandoc already does a great job translating between formats).