Beefy Boxes and Bandwidth Generously Provided by pair Networks
There's more than one way to do things

Re: Major update to

by ruzam (Curate)
on Jul 18, 2009 at 21:07 UTC ( #781382=note: print w/replies, xml ) Need Help??

in reply to Major update to

OK, maybe some will agree, maybe I'll just be shunned for saying it but I think the new look is a horrible step backwards for perldoc.

There seems to be and ugly trend in web design these days where everyone has to use highest contrast settings they can find to make a point. It's like going back to the early days of the web when everyone thought neon colour choices were cool. Granted the new look is not so bad as that, but where as I found the old layout very easy on the eyes and harmonious, I find the new layout harsh and just plain hard to read. It's a disappointing change in my eyes. Grey text in a Dark grey box sitting in a Light grey background? That might look OK... if I tweak the heck out of my monitor contrast/brightness settings first!

I can't recall if the previous layout was fixed width, but that's painfully obvious now (maybe due to the new choice of background colours?). In my browser the 'Perl Version' select box sticks out the side in way that suggests cross-browser compatibility was second (and forgotten) thought. I should be able to expand my browser window to read more of the content that I'm after. Instead all I get is more empty background. The brutal days of fixed format layout are so 2000 and late. If that's how it looked before the layout change, then I guess it just proves how badly the new colour scheme emphasizes this now.

When I have to code PHP I usually have open in a tab. I don't spend enough time with PHP to make it worth my while to stock the book shelf and keep a reference handy. But I don't have to. The PHP doc site is easy on the eyes, it flows to what ever size I make the browser window, and the search WORKS for Pete's sake. In short it's an invaluable coding resource and the user contributed comments are pure gold.

I've tried to use for my equivalent online Perl reference. It 'used' to be as easy on the eyes as the PHP site. In fact I'd say it even looked better. But I've been burned so many times now trying do a quick look up that I've stopped wasting my time there. Try searching for 'while' or 'foreach' and don't even get me going on what you get for 'if'. What does that say about our Perl language when the official documentation site can't even find the most language statements? Honestly, if I have to jump out to Google to search for Perl documentation, then I'm going to start there in the first place and skip the perldoc middle man. It's so painful to use that I've stopped trying to use it, and instead I keep the camel book next to the mouse. I could never recommend perldoc to anyone learning Perl.

The PHP documentation site is useful because (a) is uses a sane web page layout, (b) it actually has a working and complete search tool, and (c) it contains valuable user contributed comments for every function with practical examples and pitfalls. The Perldoc site has none of these (especially now).

Instead of wasting time 're-skinning' perldoc we should have spent the time making it a better perl resource. The old layout was already timeless and professional. It's the functionality that's sorely lacking.

Replies are listed 'Best First'.
Re^2: Major update to
by jj808 (Hermit) on Jul 19, 2009 at 00:51 UTC
    In my browser the 'Perl Version' select box sticks out the side in way that suggests cross-browser compatibility was second (and forgotten) thought.

    Can you let me know what browser (and version) you're using and I'll check that out. Thank you for letting me know - I test the site on quite a few different platforms and browsers, but obviously cannot replicate every combination.

    Instead of wasting time 're-skinning' perldoc we should have spent the time making it a better perl resource.

    When you say "we", what did you contribute exactly? If you had issues with the search functionality I would have been very grateful to receive suggestions and bug reports from you, or even (dare I say it) a patch.

    I'm aware that the search tool does have some limitations, and of course would be very appreciative of any help to make it better. Part of the problem you describe is because perlfunc is separated into sections, making it easy to split up into separate pages for each function name, whereas perlsyn (containing while, foreach, etc) is not, so it is more difficult to reference a specific point to document the 'while' keyword. Maybe you could contribute a page similar to perlfunc but documenting all the loop control keywords, then I could build it into the search engine?

      Firefox 2.0. Admittedly this is an older version and I don't expect full (any for that matter) support for it. Then again this is the FIRST website I've come across where the Firefox version has been an issue. But as I look at the page now, I see that you (or your predecessor) included javascript to (choke) 'document.write' the html for the perl version selector? Since when did it become cool to replace plain old html with a javascript include to write plain old html? It doesn't add a single scrap of add functionality that wasn't already available with standard html. No wonder my older browser chokes on it. Good luck when the next browser release optimization takes a different approach to what order it renders page parts/javascript and you find your select box hanging out the end again.

      Sorry if I sound harsh (and I know I do), but it's not my lot in life to fix, or assist in fixing, perldoc (my time is already filled contributing to other projects no less important than perldoc). Since you've taken on the task of spicing up the layout, it's now your lot in life to fix it. As a perldoc user, I'm telling you there are usability issues with perldoc, none of which were addressed by your update. If anything your update put new usability issues onto the site and made existing issues more obvious.

        FWIW, Solaris 10 ships with Firefox 2, so I think supporting it makes sense.

        Elda Taluta; Sarks Sark; Ark Arks

Re^2: Major update to
by wazoox (Prior) on Jul 21, 2009 at 16:14 UTC
    OK, maybe some will agree, maybe I'll just be shunned for saying it but I think the new look is a horrible step backwards for perldoc.

    I wouldn't be that harsh, but I definitely preferred the previous version. It was uncluttered, it was resizeable, readability was better. The top bar is quite annoying to me (if I want to go back to top I have a "Home" key) because it makes scrolling stutter. It sure looks better in a way, like Eclipse looks better than Emacs, or Microsoft Word looks better than Vi :)

    My suggestions :

    • instead of a large top bar, a floating toolbar on the right side would be better, as it wouldn't overlay text but the useless light grey side, it wouldn't obstruct reading and probably cause less stuttering. And as we're at it, put the search box in it so it can be more useful.
    • Really, fixed central column width? It's a step backward! Just when almost all corporate websites finally got rid of it...
    • I'd prefer a lighter and less colourful theme overall, but that's just me.
    • The perl version select box protrudes out of its box for me too : Linux, Firefox 3.5.1 as well as Konqueror 3.5.10
    • By the way, the top bar doesn't float at all in Konqueror. That only confirms that I like it better when it keeps at rest :)

    Anyway, I want to thank you very much for the hard work and the nice website. As the say goes, quid bene amat bene castigat.

Log In?

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

How do I use this? | Other CB clients
Other Users?
Others examining the Monastery: (7)
As of 2019-11-20 12:56 GMT
Find Nodes?
    Voting Booth?
    Strict and warnings: which comes first?

    Results (97 votes). Check out past polls.