[ resending... mail problems at MS, sorry if you see this twice ] Hi All, Henrik - thanks for your comprehensive message! I've set up the mailing list on haskell.org (haskelldoc@haskell.org; go to http://www.haskell.org/mailman/listinfo/haskelldoc). Let's communicate on there from now on. My thoughts on the matter appear to differ slightly from yours and Jan's, so I'll try to express my own priorities for a documentation system. - we're all agreed that what is needed is an automatic documentation-generation tool that takes annotated Haskell and delivers documentation. It's important that we don't tie ourselves to one particular documentation format, so I believe we need a separately-specified format for the in-source documentation. This is one target for attack. - a big win is that even without any annotations, you get documentation for free (i.e. hyperlinked type signatures for exported functions, class definitions, etc.). Just having this working would make we very happy :) - here's where we differ: instead of defining a new interface format and writing code to generate/parse the new format, I propose we define the format to be the same as Haskell source. Why? - we already have a pretty printer/parser for Haskell source. - we can start generating documentation from existing source straight away, without waiting for support from the compiler writers (who are generally a lazy bunch :-) It is true that by eliminating the compiler from the documentation path we lose the benefit of automatically derived types. However, the compiler often infers ugly types anyway (type synonyms may be expanded), and it's always good practice to give type signatures to every exported function. I bet there are very few functions in GHC's libraries that are exported without a type signature. Of course, I'm thinking more about "external" than "internal" documentation. But even for internal documentation, I don't think it would be a big loss not to get types if they weren't explicitly mentioned in the source. And there's an upgrade path: if we define the "interface-file" format to be exactly the same as the syntax of a Haskell module (perhaps with code optinoal), then the compiler can always just read a source file and output the same file with types filled in. I see the priorities as (a) getting the format for the documentation annotations specified, and (b) extending HDoc to do the business (and to add GHC extensions :). Cheers, Simon