nominolo at googlemail.com
Wed Jul 21 08:28:48 EDT 2010
On 21 July 2010 10:34, Simon Marlow <marlowsd at gmail.com> wrote:
> On 21/07/2010 07:13, Mark Lentczner wrote:
>>> I don't think so. I initially proposed we make it so to make
>>> launching it easier but perhaps it'll be more fun to launch it with
>>> a user-visible change. Lets try to work out a style together, I
>>> suggest we base it on Thomas style, and polish up all the pages and
>>> launch it!
>> Well..... I am of two minds on this:
>> On the one hand, we'd like to remove any possibility of lots of
>> grumbling about "going back to the old Haddock 'cause it looked
>> better", or drive to keep the old HTML backend in the code base to
>> appease people who want "that good ol'Haddock blue tables look". I
>> really want to remove that HTML backend: I hate moldy code!
>> On the other hand, I realize that what we ship as default will be the
>> "look" of Haskell code - and having it look as best as we can make it
>> is a good thing. Of course, "best" is subjective, and, well, people
>> will have to entrust our subjective taste here.
>> This brings me to a bigger discussion that promised about how to
>> handle CSS themes. Here are some non-exclusive thoughts on the
>> 1) 99% of developers are just going to go with what Haddock does "out
>> of the box". If the default theme is Classic, that is what they'll
>> do. If the default theme is something else, they'll do that.
>> 2) If we include a style switcher by default and include several
>> distinct looking themes by default, then some percentage (20%?) will
>> explore them and pick one they like. On Hackage and their home
>> computer, the choice should "stick" (the code uses a cookie to save
>> the users' choice per site.) People will still see the default theme
>> whenever they browse doc elsewhere for the first time - and they may
>> well never take the effort to switch it on other sites.
>> 3) Some projects, like Snap, will choose to publish their doc on
>> their own site rather than depend on Hackage. These projects will
>> probably want to pick a single theme and "enforce" it by not having
>> the Style menu show up, since they will want it to integrate to the
>> rest of the site's look. There is a good chance these projects will
>> write a custom theme for such use.
>> 4) It might be nice to ship initially with Classic by default, but
>> offer several, rather distinct, themes so that we can let the
>> community pick the one they like the best. Then, say three months
>> down the line, switch the popular voted theme as the default.
>> 5) It might be nice to ship initially with something wholly new and
>> really wow the community!
>> So, this leads me to ponder two questions:
>> A) How important is it to develop the Style switcher? 1, 3, and 5
>> point to it being a minor feature - perhaps used primarily by theme
>> creators. 2 and 4 suggest we fully develop to enable user choice.
>> B) How open will the community be to our designing the new look of
>> Haskell documentation?
> I vote for:
> * Work on a really nice theme that we all pretty much agree on.
> Right now, Thomas's is looking like the front runner to me.
> * Make this the default Haddock style.
> * Don't include a style switcher in the generated Haddock, at
> least by default. It's a knob that most people don't need,
> and we should focus on doing one thing really well; delegating
> choice to the user is a cop-out.
> * Nevertheless, make it easy to switch styles for developers
> who want to style their own API documentation.
> So to answer your Qs directly:
> A) not terribly important, make it an optional feature
> B) I don't think this will a problem. If you're worried then
> you could have a beta phase and ask for comments, but that's
> likely to lead to a huge thread on haskell-cafe with low
> SNR. There are enough people involved in this effort
> with the skills to produce a great result, so let's just
> do it.
As Mark said, users will most likely pick the default, so we should
just try to build the best default we can.
More information about the Haddock