This page is no longer maintained — Please continue to the home page at www.scala-lang.org

Scala library scaladoc formatting and efficient use of screen space

7 replies
ichoran
Joined: 2009-08-14,
User offline. Last seen 2 years 3 weeks ago.
I like many of the stylistic changes to the layout of the Scala library pages.  Unfortunately, along the way, the efficiency of the layout of the methods has suffered substantially, at least on my browser.

It used to be that you could get a method name and two lines of description in (on my system) 47 vertical pixels.  Now it comes to 70 for the same thing.  And, unfortunately, although the method name font is the same, the description font is actually smaller (~10%).  Thus, the new format uses about 50% more vertical space to display the same information in a sometimes-harder-to-read way.  This is partially offset by the improved tools for searching for methods, but it's hard to beat the speed at which eyes move over the page.

Given that there are a huge number of methods, and some people do not always remember which method is needed (so they must be scanned quickly visually to pick out the desired functionality), is there any chance that the format could be changed to be more compact?  Or, alternatively, is there something about my installed fonts or whatnot that is making it look less compact than it is supposed to?  If it is not just my problem, I think that by playing with spacing between lines it should be easy to get it back close to the original density without looking hopelessly crowded.  (In Gimp I was able to get back to 50 vertical pixels from 70 easily enough.)

  --Rex
Rüdiger Keller
Joined: 2010-01-24,
User offline. Last seen 42 years 45 weeks ago.
Re: Scala library scaladoc formatting and efficient use of scre

Personally, I like the new spacier layout a lot more than the cramped
old style. What surprises me is that you say the font size got smaller
in the new design. I thought font sizes were increased everywhere.

But I think we should look into increasing the font sizes even more, though.

Regarding your layout preferences, I think Donna mentioned in the past
that she thinks about adding user selectable styles, IIRC. But I don't
know what came of it.

Also, you could use some browser plugin like Stylish (1) to enforce
your own CSS styles for Scaladoc. I don't know if similar addons exist
for browsers other than Firefox, though.

Regards,
Rüdiger

(1) https://addons.mozilla.org/de/firefox/addon/stylish/

2011/5/9 Rex Kerr :
> I like many of the stylistic changes to the layout of the Scala library
> pages.  Unfortunately, along the way, the efficiency of the layout of the
> methods has suffered substantially, at least on my browser.
>
> It used to be that you could get a method name and two lines of description
> in (on my system) 47 vertical pixels.  Now it comes to 70 for the same
> thing.  And, unfortunately, although the method name font is the same, the
> description font is actually smaller (~10%).  Thus, the new format uses
> about 50% more vertical space to display the same information in a
> sometimes-harder-to-read way.  This is partially offset by the improved
> tools for searching for methods, but it's hard to beat the speed at which
> eyes move over the page.
>
> Given that there are a huge number of methods, and some people do not always
> remember which method is needed (so they must be scanned quickly visually to
> pick out the desired functionality), is there any chance that the format
> could be changed to be more compact?  Or, alternatively, is there something
> about my installed fonts or whatnot that is making it look less compact than
> it is supposed to?  If it is not just my problem, I think that by playing
> with spacing between lines it should be easy to get it back close to the
> original density without looking hopelessly crowded.  (In Gimp I was able to
> get back to 50 vertical pixels from 70 easily enough.)
>
>   --Rex
>

ichoran
Joined: 2009-08-14,
User offline. Last seen 2 years 3 weeks ago.
Re: Scala library scaladoc formatting and efficient use of scre


On Mon, May 9, 2011 at 11:07 AM, Rüdiger Keller <ruediger [dot] keller [at] googlemail [dot] com> wrote:
Personally, I like the new spacier layout a lot more than the cramped
old style.

Do you like it because it is more appealing (true for me also) or because it makes you more efficient when working (false for me)?

Also, you could use some browser plugin like Stylish (1) to enforce
your own CSS styles for Scaladoc. I don't know if similar addons exist
for browsers other than Firefox, though.

Thanks--I'll do this if necessary.  The smaller-appearing font may just be an issue of bad default fonts on my system given that you think the fonts are larger.

  --Rex

Rüdiger Keller
Joined: 2010-01-24,
User offline. Last seen 42 years 45 weeks ago.
Re: Scala library scaladoc formatting and efficient use of scre

> Do you like it because it is more appealing (true for me also) or because it makes you more efficient when working (false for me)?

For me the old Scaladoc wasn't very usable for scanning through.
Everything was just too cramped to be easily discernible. It was
always very easy to overlook what I was looking for.

With the current layout I can scroll through the document relatively
fast and still find what I need, I feel. For me it's definitely better
than before.

My gut feeling is that it's not important how many items fit on a
single screen, but how much time it takes to parse a single item. And
for that it seems to help that there's proper spacing to discern the
items from each other. Although I'm no UI designer, so I maybe wrong.
:-)

I was wondering if there is a way to highlight the member names some
more, without impeding readability and without being outright ugly.

Regards,
Rüdiger

huynhjl 2
Joined: 2011-03-26,
User offline. Last seen 42 years 45 weeks ago.
Re: Scala library scaladoc formatting and efficient use of scree

I have the same feeling about decreased efficiency due to less compact
layout for eyeballing what methods are available.
For instance looking at collection.immutable.List value members on the
old css, given the typical height of my browser window, there are
about 12 pages to scroll to see all list methods compared to 20 on the
new layout. It's less efficient because:
1) I can't see as many methods as before on one screen
2) It's harder to scroll to one area and scroll back precisely back to
where I was say to compare method description of map and collect
3) It's harder to scroll to pick up a method name while scrolling. Say
I scroll with wheel or mouse from collect trying to find map, I am
more likely to overshoot with the new layout (somehow it scrolls
faster in a way that I can't read it).
4) It seems my ultra short term visual memory (to look and remember
what methods were there without really reading them) is dependent on
number of scroll events (not on total number of methods I see), so as
I look for what methods may be relevant to my problem, if all could
fit on 4-5 pages it would be ideal. 12 pages means I'll probably have
to go back a few times to get a sense of everything. 20 pages makes
this search methodology just impractical.

On May 9, 10:08 am, Rex Kerr wrote:
> On Mon, May 9, 2011 at 11:07 AM, Rüdiger Keller <
>
> ruediger [dot] kel [dot] [dot] [dot] [at] googlemail [dot] com> wrote:
> > Personally, I like the new spacier layout a lot more than the cramped
> > old style.
>
> Do you like it because it is more appealing (true for me also) or because it
> makes you more efficient when working (false for me)?
>
> Also, you could use some browser plugin like Stylish (1) to enforce
>
> > your own CSS styles for Scaladoc. I don't know if similar addons exist
> > for browsers other than Firefox, though.
>
> Thanks--I'll do this if necessary.  The smaller-appearing font may just be
> an issue of bad default fonts on my system given that you think the fonts
> are larger.
>
>   --Rex

huynhjl 2
Joined: 2011-03-26,
User offline. Last seen 42 years 45 weeks ago.
Re: Scala library scaladoc formatting and efficient use of scree

On May 9, 10:46 am, Rüdiger Keller
wrote:
> My gut feeling is that it's not important how many items fit on a
> single screen, but how much time it takes to parse a single item. And
> for that it seems to help that there's proper spacing to discern the
> items from each other. Although I'm no UI designer, so I maybe wrong.

May be this can be tested: time different participants to find out
methods, separate in two groups: group A (compact) and B (more
spacing). Although maybe the best is just to offer an alternate css
style.

dcsobral
Joined: 2009-04-23,
User offline. Last seen 38 weeks 5 days ago.
Re: Re: Scala library scaladoc formatting and efficient use of

On Mon, May 9, 2011 at 15:25, huynhjl wrote:
> On May 9, 10:46 am, Rüdiger Keller
> wrote:
>> My gut feeling is that it's not important how many items fit on a
>> single screen, but how much time it takes to parse a single item. And
>> for that it seems to help that there's proper spacing to discern the
>> items from each other. Although I'm no UI designer, so I maybe wrong.
>
> May be this can be tested: time different participants to find out
> methods, separate in two groups: group A (compact) and B (more
> spacing).  Although maybe the best is just to offer an alternate css
> style.

It can be tested, but there are many ways of using an API
documentation. It may be used by people unfamiliar with it to learn,
it may be used by people familiar or unfamiliar with it to find what
some does, it may be used by people familiar or unfamiliar with it to
find out what does something, and it may be used by people familiar
with it to verify some detail.

"Eyeballing" is something people familiar with the API do. They scan
the page for some specific visual clue to find some information.

People unfamiliar with an API, on the other hand, may well put a
premium on having a pleasant experience than on having an efficient
interface (in fact, I read a study on GUI vs command line that showed
precisely that -- people preferred a pleasant interface even though
they were less efficient with it).

For myself, I'm happier with the new format. In fact, it is much
easier on the eyes when I'm tired, and the search feature is fast
enough to overcome the space "problem".

One change I *would* like would be for the member search box to be
moved to right below the package/trait/class/object declaration, and
have it and everything above be turned into a separate frame, so it
wouldn't scroll. That would decrease the space for members themselves
even more, but I find I often have to scroll up to look up some type
parameter detail, and even more to enter a separate search.

I'd also like keyboard shortcuts. Maybe they exist already?

Philippe Lhoste
Joined: 2010-09-02,
User offline. Last seen 42 years 45 weeks ago.
Re: Scala library scaladoc formatting and efficient use of scree

On 09/05/2011 17:07, Rüdiger Keller wrote:
> Also, you could use some browser plugin like Stylish (1) to enforce
> your own CSS styles for Scaladoc. I don't know if similar addons exist
> for browsers other than Firefox, though.

In lot of browsers, you can define user style sheets.

Copyright © 2012 École Polytechnique Fédérale de Lausanne (EPFL), Lausanne, Switzerland