[Haskell-cafe] Re: Writing great documentation

[Duncan Coutts]

On Fri, 2009-11-13 at 23:20 +0200, Max Rabkin wrote:
> On Fri, Nov 13, 2009 at 10:58 PM, Simon Michael <simon at joyful.com> wrote:
> > A very common problem with online docs is fragmentation.
> 
> Absolutely! Is it possible to include non-haddock documentation in a
> cabal package. Is it possible to have it readable on Hackage?

Not yet.

Want to volunteer?

http://hackage.haskell.org/trac/hackage/ticket/330

It's partly a matter of tasteful design and partly implementation. The
same person/people do not need to do both bits. Thrashing out a detailed
and workable design would get us most of the way there.

> I think this would help with the fragmentation and versioning issues.

Yes, I agree.

> One option is to have haddock-only modules for non-reference
> documentation (xmonad-contrib does this), and I think at the moment it
> is a good option, but it does have disadvantages. It may not be clear
> from the outline where documentation can be found, and it clutters up
> the module namespace. Perhaps we could add support for a
> Documentation-Modules field in cabal files, which would separate these
> modules in the outline, and not install them but only their
> documentation.

I rather like the idea of using markdown (pandoc) for separate
non-reference docs like man pages, tutorials, user guides etc rather
than trying to make haddock do everything.

Duncan