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/
[email protected]
irc: mtnviewmark
_______________________________________________
Haskell-Cafe mailing list
[email protected]
http://www.haskell.org/mailman/listinfo/haskell-cafe
