Beefy Boxes and Bandwidth Generously Provided by pair Networks
Don't ask to ask, just ask
 
PerlMonks  

Re^3: Major update to perldoc.perl.org (functional)

by tye (Cardinal)
on Jul 17, 2009 at 16:25 UTC ( #781092=note: print w/ replies, xml ) Need Help??


in reply to Re^2: Major update to perldoc.perl.org
in thread Major update to perldoc.perl.org

I hovered over moritz's three links and was a bit surprised to not see "ours truly" included. moritz is so polite. ;)

And, before I go any further, I would like to extend my sincere thanks to jj808 for the hard work (on an important site) and for announcing the changes here. I hope he won't mind the ensuing discussion. I'm unlikely to privately communicate critiques of his work since I have the opportunity to do so with much less effort as part of this discussion.

I don't want to discount the visual changes that I'm sure jj808 worked hard on. As you may have suspected from visiting this clunky-looking site that I hack upon, I don't really notice fonts or colors much (except when they make things hard to read). So I'm genuinely sorry that I don't have much praise to offer about "the look". I go to perldoc because I want to read some text and it is often the most convenient way to get to that text in a format that is easy to read. I am truly thankful that jj808 worked hard on the new look and I hope that it is well appreciated by normal people who notice that stuff. :)

I also would like to offer great praise to jj808 for choosing to leave links underlined so that I can find them (and without learning some alternate visual cue).

The Perl documentation (in the new layout) is quite easy to read. The "syntax coloring" on the code snippets is done subtly enough that it is only slightly distracting (the bright red for sub names is an exception in both that it isn't subtle and actually makes the names hard to read).

The highlighted boxes around in-line code snippets make it easy to scan for keywords and bits of syntax while they also don't seem to disrupt my reading nor make the code hard to read. Good job!

But having such an important feature (search) not work w/o javascript is something I would consider unacceptable. I find it even more galling for a Perl site (but we can to be self-righteous, can't we). I know that many people appreciate many of the interface options that become possible with javascript (I do sometimes but I even more often find that I prefer the consistency of an HTML-only interface) but providing a fall-back is just polite.

In this particular case, I'm not upset except in abstract at this point because I don't use perldoc's search feature anyway. I use PerlMonks' to 'search' perldoc, typing (for example) doc://$; into the PerlMonks 'search' box to jump right to the desired documentation (and this still works w/o need of javascript, thankfully). When doing full-text searching of Perl documentation, I tend to use 'grep' against my local perl/pod/*.pod (or equivalents, usually using vi as my doc reader). And now I know to not try the search box so I'll just use google w/ site:perldoc.perl.org when I want to find documents that mention "all of the following words".

So those who miss a useful search due to lack of javascript (perhaps just by choice) have at least two alternatives for searching perldoc.perl.org (use PerlMonks or use google).

So I would like to gently encourage jj808 to allow non-javascript environments to work more smoothly at such an important site (certainly javascript isn't intrinsically required for any previously-available functionality there, such as searching, since it worked w/o javascript before).

I realize that the new search functionality is more than just interface tweaking. And I noticed and appreciate the "this is the best match but you can look at the list of other matches if you want to" feature (a feature I've long wanted to add to PerlMonks). But the site should at least offer a less-smooth search feature in the absense of javascript (IMO, obviously).

I'm sure some will ask "why would you ever not have javascript enabled"? In this particular case, I would go out of my way to disable javascript just to get rid of the "floating" heading bar. There are lots of annoyances inflicted by javascript so I prefer to opt-in to javascript only for sites where they offer features that really require such functionality and where the site does an excellent job of not annoying me (javascript is often used to make particularly annoying advertisements, for example; but I often find javascripters' interface choices annoying enough as well). I'm sure others have other reasons to browse w/o javascript (corporate security policy, their own security choices, their particular environment, etc.).

I also encourage providing a link to set a cookie that turns off the "you don't have javascript" notice (or at least replace it with something much less conspicuous). I understand the desire (and wisdom) of making it very obvious to new visitors the likely reason why the site is behaving "a bit odd". But I also understand visitors refusing or being unable to enable javascript and getting quite annoyed at the visual noise on every screen.

I also encourage providing a way to set a cookie saying that one doesn't want the floating header so those with javascript enabled can get rid of it (some will surely find it useful but it is unusual enough that I'm sure some will just find it an annoyance), perhaps triggered from an 'x' element on the bar.

Finally, I will once again tilt against the windmill of webpages that don't know how to resize. I'm certain that your new design would be nearly unusable if I visited from my zaurus (or other small-format browsers I've been known to use). I can adjust the width of my browser window as much as I want to and your new layout resolutely refuses to acknowledge my choice (or limitations). If I want to get a larger section of documentation showing on one part of my screen as a reference while I'm doing work based on it in another window, you have greatly limited my choices.

I realize that there is a resolute meme that CSS is king and tables (for layout) are evil and even bow to the strong motivation for "pixel-perfect" web layout in the face of many web advertisement schemes. And I love CSS for much styling. But CSS is fundamentally broken when it comes to doing layout (as can be seen by people spending days trying to do simple things with it and the fact that almost nobody is cabaple of producing a layout with CSS that is capable of resizing well). So I'll just challenge you to prove me wrong (as I always do) and get your CSS-based layout to resize to still be readable when given a quite narrow window and to use more horizontal space when it is offered to it.

Thanks again for your hard work, jj808! I hope you find my critique and criticism useful.

- tye        


Comment on Re^3: Major update to perldoc.perl.org (functional)
Re^4: Major update to perldoc.perl.org (functional)
by SuicideJunkie (Priest) on Jul 17, 2009 at 17:42 UTC

    Well said, tye

    My browser is rarely set to 1000px wide, personally. 800 is common, but I'll shrink it to 500 or so when I'm coding on the side and want to see perldoc at the same time (the code editor gets priority for screen space). Wider when I'm reading stories or other big blocks of text. I have lots of stuff open, and they all have to play nice and share the desktop space.
    On the other hand, I find that a lot of the older generation people I know always fullscreen everything. 1280px to 1600px for them no matter what.

    Dynamic layout is a great feature.

    PS: I suspect that most people who have disabled javascript will also disable cookies, particularly cookies that outlast the session. Having a cookie disable the warning would not be effective in those situations.

    UPDATE:
    Sometimes you just have to do it yourself:
    How to make perldoc.perl.org resizable too!

      So why do people disable cookies? I assume that it is out of some desire to deny information to advertisers. I guess they find it annoying to have advertisements that better target them? :)

      And what is the reasonable replacement for a cookie (or two) here? Certainly, I could add custom CSS to hide such bits. But browsers don't make it easy to add custom CSS in my experience (nearly the opposite). And browsers don't let the site make suggestions of CSS to add for the user so such a solution is significantly less useful in not being able to be offered to the user with a simple click.

      I have practical reasons for disabling javascript. I'm sure there are people who disable cookies. I'm sure there are a lot of people who have tools that disable certain kinds of cookies (trying to focus on cookies used by advertisers). But I've heard a lot of arguments against disabling anonymous posting at PerlMonks and I don't think that "I refuse to accept any cookies!" has come up much at all.

      In any case, if somebody routinely refuses cookies, it seems reasonable to me to allow them to decide to accept some cookies that are very clearly only there to let them customize a couple of features (no "tracking number" included) or to not accept them and take on the burden of rolling their own customization.

      - tye        

Re^4: Major update to perldoc.perl.org (functional)
by DStaal (Chaplain) on Jul 17, 2009 at 17:50 UTC

    CSS is actually great at doing dynamic layouts... If you let it. The designer just has to get out of their head the idea that they are going to exactly control the actual size of everything, and design around the idea that they are going to design relative sizes, with possible minimums and maximums.

Re^4: Major update to perldoc.perl.org (functional)
by jdporter (Canon) on Jul 17, 2009 at 17:56 UTC
    so I'll just use google w/ site:perldoc.perl.org when I want to find documents that mention "all of the following words".

    Maybe we should change perldoc:// to use google. Then one can easily search for all these words "and this multi-word expression".

    Between the mind which plans and the hands which build, there must be a mediator... and this mediator must be the heart.

      I finally grok this suggestion and I think it is an excellent one. To be clear, perldoc:// is currently useless (and has always been) if javascript is disabled (for perldoc.perl.org) and having perldoc:// run a google search would be better.

      Update: perldoc:// now links to google searches: glob, if (doc:// still links to a "best guess": glob, if).

      - tye        

        I think
        http://www.google.com/search?q=...&sitesearch=perldoc.perl.org
        would be slightly better than
        http://www.google.com/search?q=...%20site%3Aperldoc.perl.org
        since it makes it slightly easier to refine or change the query.
Re^4: Major update to perldoc.perl.org (functional)
by jj808 (Hermit) on Jul 17, 2009 at 23:03 UTC

    Hi Tye, thanks for your comments - I just wanted to point out one thing about search, it has always required JavaScript. Due to the way the site is hosted by perl.org, there is no server-side processing, the entire site is just flat HTML and JS files.

    For this reason a cookie-based system to suppress the noscript warning would not work, as the only way I could implement it would be to use JavaScript to read the cookie, somewhat defeating the point! :-)

    Incidentally I added the noscript warning due to complaints I'd received about the previous site which did not warn if JS was disabled, just goes to show it's impossible to please everyone...

      Thank you for the update. I guess I proved that I don't use the on-site search functionality. May I suggest you make a graceful fall-back for non-javascript as a form that submits a search to google? (like you already include in your "view all results")

      I see you already have class="noscript" so people can learn to add custom CSS to their browswer set-up and remove the notice with minimal work themselves.

      As for the floating bar, you could use javascript-based cookies for that preference.

      - tye        

      Hi JJ,

      I'm prolly one of those who complained about not being told everything needs JS-- as a non-JSer I always appreciate being let known that hey, this site uses JS for stuff (and often it's also nice to know what for, because one of the reasons I specifically keep it off is to avoid MooToolsy drag-n-drop fading blitzkrieg Nintendo-generation short-attention-span superfeatures and that sort of thing). Knowing scripting is used for "this" "that" etc I think is always thoughtful for a web dev to do, as there's nothing more frustrating that not figuring out why something doesn't work, when it's because your browser isn't supporting applets/cookies/java/scripts/css/other things you can never guarantee a user agent can or does support. Of course, the goal is to have the user never notice, have pages built with progressive enhancement, but when that's not possible, a small message is nice.

      That said, it shouldn't have to take up a huge amount of space on the page or anything. Most sites get away with a small message at the top of the screen. Without cookies I don't see how people could have a "don't show me this again" option so, maybe the box could be moved somewhere else, but otherwise, I find it more valuable on-page even if some find it annoying.

Re^4: Major update to perldoc.perl.org (functional)
by Anonymous Monk on Jul 23, 2009 at 15:16 UTC
    I really really prefer the old perldoc to the new one, partially because of the color scheme, but mostly because I use a widescreen monitor, and pages that mimic an 8 1/2 x 11 look with a fixed width waste 50% of the space. This is made worse when half of that is sidebars, meaning the text lines in the middle are hideously short -- suitable for a string of blurbs as opposed to a series of paragraphs. Basically, this dictates preferences to the user which should be left up to the user. That is bad policy.
    ...the fact that almost nobody is cabaple of producing a layout with CSS that is capable of resizing well...
    I want to point out that this is just false. CSS accepts a % for the top/right/left/bottom in absolutely positioned elements to control their size relative to the window (or container). As long as all the containers are done that way, the page will resize perfectly.

    Vis, the javascript search, as jj pointed out, this is so you can use it downloaded at home without having to run a server and do some ridiculous installation, which is a very nice feature.

    I do web development and I no longer make provision for people who have javascript disabled; it's simply tedious. IMO, if you want something to work without js you can code it yourself ;) Also, a major purpose of js (and ajax) is reduce unnecessary server side processing. By trying to discourage it's use, you are promoting senseless net congestion and all manner of bloated server-side "technology". Maybe perlmonks wouldn't be so ridiculously slow if you tried it -- clearly we will never find out.

    I still like using lynx occasionally, but I don't go around complaining about sites that have not made themselves properly compatible with a text only browser...

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://781092]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others chanting in the Monastery: (7)
As of 2014-07-31 22:41 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    My favorite superfluous repetitious redundant duplicative phrase is:









    Results (254 votes), past polls