CSS Themes

[Thomas Schilling]

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
>> matter:
>>
>> 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?
>>
>> Thoughts?
>
> 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.

+1

As Mark said, users will most likely pick the default, so we should
just try to build the best default we can.