[Haskell-cafe] Haddock New Look Survey results

[Mark Lentczner]

Thank you to all who took the Haddock New Look Survey.  We got a 161 responses. Some graphs of the results can be found here:
http://www.ozonehouse.com/mark/snap-xhtml/Haddock-Survey-Summary.pdf
    
I've read through all of the comments, and I'd like to share some initial thoughts with you:

• Source links are indeed still supported in Haddock, I just happened to generate those sample pages with it turned off. Sorry for any confusion. The functionality remains exactly like it is in Haddock today.

• I also failed to turn off all the "alternate style" bits on the index page, and many of you found it, explored the other styles, and then wondered why it failed on the module pages. I had intended for the survey to just give pages in the new style, and missed updating the index page. In the new Haddock, you can specify which "themes" you want to render your documentation with. If you include more than one, the pages have a "style switcher" menu added. The default themes that will come with Haddock include "Classic" which is a pretty faithful recreation of the current look.

• Many great suggestions were made about ways to improve the UI experience of Synopsis drawer. Of course, the web is hardly a full featured UI framework, and to implement many of them we would have to decide to move to a much larger JavaScript framework. At present, Haddock attempts to use JavaScript very lightly, and only needs one small .js file. I think we are planning on keeping it that way for now.

• Several people mentioned that perhaps we should have "user preferences" for things like where the Synopsis section goes. This is possible (the "style switcher" menu above uses such a preference), but know that a page can only set a cookie for a site. So if we do such things, they will stick per site, and users will have to choose their preference for each new site of Haddock docs they browse to. Fortunately, all of Hackage would count as one site, as does your local machine, and those two settings probably cover the bulk one's use.

There were many many good suggestions, reported problems, and observations among the comments. I'm pulling together a short of list with the Haddock team of high priority changes based on these to be completed before the first release. To be sure, this will include:
- fixing the layout issues on Firefox & Chrome
- improving the expanding/collapsing behavior in module lists

The most difficult issue is how to handle the Synopsis. As evident both from the multiple choice question in the survey, and from the comments, there is no clear consensus. While 2/3rds of you like the Synopsis drawer, there is a wide range of how it should look and operate. Another 1/5th want it back where it was, in-line with the page. There were many other suggestions as well. I'm going to go have to spend some time mulling what to do.

Finally, thanks for the huge amount of positive feedback. When working on open source, often on speculation that it is what the community will want, it is really great to hear that you've done good! I realize that there is no way that such a change as this can please everyone 100%, but I'm glad to see that we are, on the whole, people are really happy with the work.

    - Mark

Mark Lentczner
http://www.ozonehouse.com/mark/
mark at glyphic.com
irc: mtnviewmark


-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.haskell.org/pipermail/haskell-cafe/attachments/20100806/850f74f2/attachment.html