Web Fundamentals: A handbook for best practices | Hacker News Reader

Web Fundamentals: A handbook for best practices

developers.google.com

379 pointsisopod64 comments

I don't find this site to be a fundamentally good example of usability.

It's not TERRIBLE, but given that they're speaking from a position of high-authority, it should be better.

Three examples:

(1) https://developers.google.com/web/fundamentals/documentation... - What am I supposed to click? The "2 guides" thingy looks like a button. No. Not clickable. But then just below are two identically colored "Create Amazing Forms" and "Add Touch to Your Site". Easily solvable with (a) buttons (b) underlined links (c) consistent navigation colors

(2) Click on "Getting Started" in the top navigation section. Would you expect that the text should now be bold, as it was on the home screen indicating which page / section I'm on?

(3) Back to this page "https://developers.google.com/web/fundamentals/documentation... - why is there a cookie-crumb nav element in Documentation that's not present on other subs like https://developers.google.com/web/fundamentals/resources/sty...

In their defense, I understand that their audience is "developers" who are going to be able to solve poor UX and find what they want.

But still feels like a moment to eat your own dogfood . . .

Certainly! Good call. We soft launched the site today and are still very actively improving things. I like your suggestions though. I broke the menu and a fix is heading out soon. I'll file the others so we can get them addressed. [EDITED.]

Added bugs https://github.com/google/WebFundamentals/issues 9,10,11

a) Sorry to be a grumbler, I know how hard it is to launch anything. You rock for instantly adding these to git and I appreciate the response.

b) I spent a few more mins on the site after posting the comment, the lesson content is very strong.

I wonder if the content would be better served by removing the stuff below your headline on https://developers.google.com/web/fundamentals/ - eg those links are where I immediately got lost. If I'd clicked the Get Started and nothing else I would have had a much smoother experience.

:) we will certainly get them sorted. We are also looking at the nav and the quick access to the content so the links are more easily accessible.

New best practice: do a cold launch with announcement, then call it a soft launch if bugs pop up.

We didn't do any announcement at all. We sent it to some developers for feedback. It has kind of put the kybosh on me announcing this properly at Google IO.

Its a giude about web UI best practices, and the icons symbolizing the different topics are not clickable?

Besides, I didn't even notice that some of the headlines/h2s in the subsequent pages are actually clickable.

Then, they actually enlosed their <video> elements inside a <a> tag. So now, when I click on the controls of a video, it will open the linked page. No way to use the video's controls without leaving the page I am reading.

Three basic errors found in under a minute on a simple text site. I don't think I want to take any UI design advice from that person.

Thanks for taking a look! We soft launched yesterday; this is definitely still a work in progress.

>the icons symbolizing the different topics are not clickable

https://github.com/google/WebFundamentals/issues/1

>headlines/h2s

https://github.com/google/WebFundamentals/issues/52

>they actually enlosed their <video> elements inside a <a> tag

Are you referring to the video on this page?

https://developers.google.com/web/fundamentals/documentation...

Clicking the non-control parts of the video opens a demo page with the responsive HTML/CSS demoed in the video. The controls still work, at least in Chrome 34 on Mavericks. If you're talking about something else, could you file an issue on GitHub?

https://github.com/google/WebFundamentals/issues/new

The advice on min-width vs min-device-width strikes me as controversial:

  Therefore, you should avoid using *-device-width, since the
  page won’t respond when the desktop browser window is
  resized.

GMail, Facebook, New York Times, and lots of other smart folks don't show their mobile-web versions if you make the browser viewport very small. Their sites have min-width ~980px when viewed on desktop.

I imagine this is because (a) their mobile sites use different interactions that require different DOM and JS, not just different CSS styles, and/or (b) those different interactions might not be appropriate on desktop even if you shrink the viewport and/or (c) it's confusing for the site to work differently when you resize your window and/or (d) they don't want to send unused JS/DOM to devices that aren't going to use it.

Any thoughts, kinlan?

Good point. In lots of cases these sites are actually doing the detection of the device class on the server and never returning a fully responsive site in the first place. There is certainly a balance to be had on responsive vs adaptive, in this case with this piece of guidance it is to give developers and users the chance to adapt more appropriately to the screen constraints at any time. Min-device-width is pretty much permenant so it is harder to adapt to when the user is on a big screen but only usng half of it.

For most content based sites there is not a huge amount of reason to have drastically different html, CSS or js. For apps we are yet to cover that fully.

Personally I wish they did. On my 13" MacBook, I want to be able to make those windows smaller and still be able to see the content without having to pan back and forth or zoom the content.

There's also some good technical reasons that PPK pointed out in the issue he raised (https://github.com/google/WebFundamentals/issues/20).

The icons are broken in firefox because you used a webfont wich is hosted on another domain.

Edit: Just saw that you already know about this: https://github.com/google/WebFundamentals/issues/13

--- Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at https://web-central.appspot.com/web/essentials/icons/icons.w.... This can be fixed by moving the resource to the same domain or enabling CORS.

Thanks for the information. I have updated the tickets (also #2). We will get it sorted asap - there are some plumbing issues that I need to resolve on the main site to get this sorted.

Icons should be fixed now.

a) How is one supposed to know what is clickable on that webpage?

b) Why are the circles not valid click targets?

c) If you say this -> "To deliver the best user experience, we must deliver content as quickly as possible (<1 second)" then why does your section on Critical Rendering Path show the optimized page load in 1.5 seconds?

Great points. thanks for the feedback. I have an open issue to ensure that it is clearer to understand which elements are clickable. (b) is frustrating. (c) when I tested it today it loaded in 0.6 seconds, but I will work with Ilya on getting this sorted asap (https://github.com/google/WebFundamentals/issues/14).

For issue 14, I believe he meant that the image on the page (https://developers.google.com/web/fundamentals/documentation...) shows the optimized rendering taking 1.5 seconds, not that the page itself loads in 1.5 seconds.

> a) How is one supposed to know what is clickable on that webpage?

And the candidates are, look at the HTML and JS code, write a simulator that can in effect click on each pixel on the page, submit a question to Stack Overflow, click on every candidate spot on the page. May I have the envelope, please (drum roll)? And the winner is, click on every candidate spot on the page! And the winner thanks all the losers and wishes them still less luck the next time!

But, we already knew all this, right?

Was the role in user interface and user experience at Google really that important?

"Mystery meat navigation", as that is commonly called, makes it sound so ugly.. I have a happy name for it, "the bit in Maniac Mansion where you have to find something in a pitch black room".

>a) How is one supposed to know what is clickable on that webpage?

The mouse pointer turns into a hand?

That's not very helpful on a touch device

the circles are not clickable at the lower part of the page, but in the drop down menu they are clickable. Seems inconsistent to me.

Repository for filing issues: https://github.com/google/WebFundamentals/issues

Most of the responses are somewhat negative (although helpful), but as a back-end'ish guy trying to learn full stack, CSS is the one thing that is nails on the chalkboard for me to learn properly. I've got this bookmarked as a reference to succinctly explain these basics; Thanks!

You might like this, it was posted here in the last few months. A really well done CSS selector tutorial (and a really good example of how teaching can be done on the web w/ interactive exercises).

https://flukeout.github.io/

I thought this was an excellent tutorial on css vs positioning: http://learnlayout.com/

I'd recommend CSS Mastery. While a lot of the browser hacks are completely outdated, the sections on CSS fundamentals helped me a lot.

It was the first time I went through an explanation of CSS layout and positioning and felt comfortable turning something on paper into a UI on screen that looked exactly how I wanted it to look. Before the book I relied heavily on trial and error. Now I can look at something, write some markup and CSS, and it does exactly what I want.

I really hope this design pattern of huge fonts across the screen is a fad and will go away sometime soon. That and parallax scrolling. It's bugging me to no end for some reason. Am I alone in this?

No, I can't stand design which say "you read our heading, great! Now scroll a bit to read the next 5 words" either.

It sucks but it's a great marketing gimmick.

If Joe Blow managed to lift his fat finger to click and scroll - he'll be eligible to read more exciting stuff and eventually be opted-in and be sold to.

From the other point of view - scrolling down requires minimal brain cycles (i.e. where is the next link to click?) - and people love doing that to absorb the whole content without thinking.

Sort of like getting a free massage.

Please don't tell me what "people love" without evidence for the stated fact. I am a subset of people and I don't love it.

In this case our primary call to action was to get people into the getting started guide, which it does do. I will try and tone it down though.

Note / is valid in street address (e.g. Unit 22 1/2). I believe the provided regex [a-zA-Z\d\s\-\,\#\.\+]+ would reject that.

Kinda strange I'm the first to compliment them on a very nice resource. Would've loved to have had this when I was starting out. Google can do some good things people.

I see the performance stuff as the most useful. Otherwise, the general layout/responsive design pointers are pretty much common knowledge at this point (or so I think).

Great starting point, would be nice to integrate with Pagespeed.

I have it on the plan to have PageSpeed on the front page and then it gives you a targeted doc plan. https://github.com/google/WebFundamentals/issues/12

Edit: there is also information that is common knowledge for a lot of advanced developers but for the rest of developers there are not many places that present a similar narrative.

This thread is full of people nit-picking design concerns with this open source resource, however the actual content in this seems to be top-notch!

While there's good advice contained within, the phrase "best practices" in the title may already be off-putting to some, because of how overused it's been to describe anything that anyone at one time thought was a good idea, leading to assuming that there is always only one "best" way to do something. In my experience, there never is.

I'd suggest not to use a condensed typeface for the editorial header. It makes the paragraph look weird and is difficult to read.

Was a bit surprised by how they managed to display my full name from my Google account in the example videos. Then I remembered ;)

Frankly, on so many levels, this site is just fucking terrible. It would not be particularly hyperbolic to suggest that it actually summarizes much of what is wrong with the internet today. Let's see:

(1) 'Web'. There is more to the internet than web. When writing content for aspiring developers, can we not accept broader and more accurate terms in their education?

(2) After clicking through to a page entitled Web Fundamentals: A handbook for best practices, and then Get Started (WTF? I thought this was a reference, not a process!) I get 'Your First Multi-Screen Site'. What? I was presented with "handbook for best practices", and I got "hand-holding simplified idiot guide aiming for feel good first outcomes". How could anyone think this is semantically justified?

(3) The produced page screenshots are near-on unreadable with shitty contrast and few realistic elements (forms, small social or content-suggestive icons, etc.)

(4) The text under 'What will I learn' is so small as to be unreadable on a 17" laptop (~latest Firefox, Linux).

(5) The fundamental structure of the 'course' (not a handbook anymore, eh?) makes little sense given the tiny number of lessons (ie. 2). An alternate overall approach to content organization would be been more intuitive.

(6) There are Chinese characters all over the site, because someone's nappyJS framework figured nobody would ever interpret them has having any meaning. Well, here's a wakeup call from China. There's more of us than there are of you. (and I say that as a westerner who learned Chinese ... I believe tptacek and others here also have strong Chinese reading skills).

(7) Separation of concerns fail: create a skeleton view of the page with content but without styling. Design is secondary to content. Figure out what you communicate before dreaming up methods to achieve it.

(8) Use of terms without introduction, eg. IA, padding. Does wonders for intelligibility! Any editor from the old-school print and paper world would have caught this in a flash, if the author got off their high horse, recognized the lack of novelty in fundamental communications processes, and accepted some criticism while espousing "the fundamental way to be just like them" (for idiots edition; paraphrased from original page title and ridiculous semanting hoop-jump that led to this cesspit).

(9) Contrast of prescriptive "As a web developer, you are expected to..." stuff and hand-holding present continuous pronouns ("We will...") comes across as condescending and pathetic. While this may be normal amongst certain segments of US communications, the rest of the world just laughs along ... at you, not with you.

(10) Use of terribly US-centric and verbose expressions such as 'judgement call'. Heard of "making a decision"? Well, it's a huge improvement: for the majority of its global users, English is a second language. (Hey, look at that! A useful fundamental!) And guess what? It's even more concise when you use the word "decide", which has the secondary benefit of using even simpler grammar! (As in "Decide how to integrate Dogecoins", or "Decide when to write authoritatively")

(11) Ridiculous gaps in lists due to poor styling that cannot degrade if Javascript has been disabled or is not present, eg. in partially loaded pages, accessibility-oriented consumers, text-only browsers, security-conscious browsers.

(12) Despite claims to be part of a larger, mobile-focused course (Hey, I thought this was an authoritative best-practices handbook? Oh wait...), nowhere is there mention of the reality of mobile: the network is slow, the network is unrealiable. Cache-control? Forget it. Emerging standards for offline, open web applications? Forget it.

(13) Why the hell would you use a link to a second page to "show full sample" when on mobile? You'd clearly want to load that as part of the main page (Oh wait, you did! Why not load it again?), as round-trip times for page loads are terrible. (Oh wait, it seems the author has never written an actual mobile website outside of shiny blingphone-optimized first-world 5G always-on-wifi environments. Like, Chai latte with skim, baby. Is that cocoa organic? Oh, you don't know? No thanks. Where was I?)

(14) Use of flash? 2014? What? Use of flash? What?

(15) Calling software features 'technologies' is about as transparent as how much I would like to physically accelerate an extremity of my body towards the upper frontal portion of the author, particularly when people from outside of your ... cough ... culture try to comprehend it. (Easy rule: technology's physical, software's not)

(16) Inconsistent capitalization.

(17) Use of video on mobile-targeted sites without discussion of pitfalls? Really?

Not sure about others here, but frankly I'm sick of Google trying to be the be-all and end-all of the internet (+1!), and polluting it with touchy-feely-device content ("CONSUME! CONSUME!") like this holier-than-thou idiotville garbage that tries to gloss over the ugly-as-butt reality of web content authorship and network connectivity problems. Just... fail.

> (15) Calling software features 'technologies' is [non-]transparent ... (Easy rule: technology's physical, software's not)

If we're going to be pedantic about it, let's consult our friends at dictionary.com.

Technology, n.

1. the branch of knowledge that deals with the creation and use of technical means and their interrelation with life, society, and the environment, drawing upon such subjects as industrial arts, engineering, applied science, and pure science.

2. the terminology of an art, science, etc.; technical nomenclature.

3. a scientific or industrial process, invention, method, or the like.

4. the sum of the ways in which social groups provide themselves with the material objects of their civilization.

I have highlighted the bits under which software counts as technology in one sense or another. (EDIT: I have now.) There is also an aspect of common usage with an Arthur C Clarke sort of definition - "that which, sufficiently advanced, is indistinguishable from magic". When my techno-semi-literate parents gaze with wonder at their iPhones and say "It's amazing what they can do with technology nowadays", are they talking about the hardware or iOS? Both.

I agree with much of the rest.

I'll admit, I found the it frustrating at first. It was difficult to navigate through the site and parts of it didn't look nice. But it is a work in progress. I think there's a lot of potential here and I'm really excited about it.

As someone who's really ramped up their self-studying of web development over the past few months, I think this will eventually be a great resource for me and others. I've yet to contribute to an open-source project but I think this will be my first one.

I am not sure of the tip to associate labels with every form input.

In many cases placeholders and surrounding text by itself is sufficient.

Most launch pages doesn't have a email address label associated with each including the avocode example posted on HN today.

Do people still use form autocomplete client side? I thought there was a terrible "bug" in sites stealing your address and email by putting in a hidden inputs with these autocomplete attributes?

The requested URL /web/fundamentals/resources/samples/getting-started/your-first-multi-screen-site/addvideo was not found on this server.

Hmm. For me it correctly redirects to the appropriate path on google-developers.appspot.com. Could you verify that you're still having trouble and if so file an issue describing where specifically you encountered the dead link?

https://github.com/google/WebFundamentals/issues/new

I rather not assist Google in any capacity whatsoever, sorry.

Somewhat surprised there's no discussion of security going on here - even at a design level, there are some useful considerations.

Good point. We're planning to add more content later. What's on the site now is what we were able to write in the first 6 weeks. The goal is to eventually grow this to be as thorough as developers.android.com or iOS Dev Center (but for the web).

i like graphic design of the site, especially the hanzi interspersed throughout. i've no idea what the "remember" boxes say, although it might sound like 记 from "to remember," based on it looking like 迹?

There are errors in this.

Eek. Can you let me know where and I will get them fixed as soon as possible.

why no +1 button?

I believe this was soft-launched today and not yet ready for general consumption.

My guess: they talk a lot about performance and adding social media buttons to a site really slows it down. Of course, there are ways to mitigate this (load them after page load) but that still makes the page look like it loaded slower.

With the title 'Web Fundamentals', from Google there might be something good there to learn. Butm three points:

(1) "Multi-screen" is not in my Funk and Wagnalls and, thus, has a specialized meaning, is a 'term', and needs at least a definition and likely also motivation, explanation, and examples. So, the author of this course on writing Web sites doesn't know how to write.

(2) He says that the course will end with a 'landing page'. I don't really know what the heck that is. Once again he is long on obscure terminology and short on definitions.

Apparently he likes his own jargon. Bummer.

(3) His page has a black background with faint type that is nearly impossible to read. In addition he has some 'swaths' of light across the text making the page next to impossible to read. Maybe if I 'selected' the text from the page or got the HTML and extracted the text I could read it, but what he has is not good.

Bummer.

Hi, We will get these sorted. I was surprised that this got picked up so early as we were just starting to canvas feedback from developers, so it still a work in progress.

Multi-screen/Multi-device was the term we chose because mobile-first is a very very loaded and our goal is to target mobile as a base but ensure everyone builds up from that experience. But you are correct, it needs to be introduced.

[Edit] - adding bugs https://github.com/google/WebFundamentals/issues/17 https://github.com/google/WebFundamentals/issues/18

The medicine I am giving you may taste bitter, but a result should be some much better technical writing. So far, 'multi-screen' is just jargon of an in-group, really 'in' because it wasn't clear to me, and my background in computing is plenty deep.

You still just don't 'get it': E.g., that 'mobile', smartphones, wrist watches, glasses, or tablets are the main issue just was not at all clear to an 'outsider.

"Multi-screen', no matter how common and comfortable you and your colleagues are with the term, just is not, Not, NOT clear. Here is an example: Do you mean a workstation with four screens? Is that what you are talking about, that is, software from one Web site that makes separate use of each of the four screens? How the heck to know?

Or maybe you meant essentially multiple windows, treated separately, from one Web site on one physical screen? How the heck to know?

Or, essentially every Web site now is 'multi-screen' in that it works if the resolution on a screen is 640 x 480, ..., 3000 x 4096 and lots of other screen resolutions and physical screen sizes. Also each Web site is 'multi-screen' in the sense that 500 people, each in a different location, can be viewing Web pages from the site all at the same time, that is, the site is serving 500 screens.

Instead, apparently by 'multi-screen' you mean the different screens 'types' on end user devices from workstations, desktops, laptops, and tablets down to smart phones and maybe wrist watches and glasses. But if each of these devices has a standard Web browser, then what is the significant difference? Maybe the difference is swipes versus clicks or some such, in which case 'screen' is not really the point.

The issue is being clear when using words with meanings that are not in a standard dictionary. Such a word is a 'term' and, thus, needs at least a definition and likely also motivation, explanation, and examples. Else are on the way to jargon and gibberish.

Such bad writing is endemic in practical computing and a big, huge, problem for the field. Even computer science very much needs to 'up its game' to catch up with physics and especially mathematics.

Apparently my little lesson in good technical writing 101 rubbed some feathers the wrong way, but the lesson stands -- good definitions are crucial, and 'multi-screen' screams out for a good definition.

It still is not clear, without a lot of guessing, just what is the significance of any definition of 'multi-screen' for building a Web site. That is, the Web site mostly shouldn't care. E.g., I'm building a Web site, and the pages look fine, and there is no logic at all in either the server or what is sent to the client on what the heck the screen size is. My solution: Each Web page is exactly 800 pixels wide. Period. If the actual window used on the client device is less than 800 pixels wide, then the client device is welcome to add horizontal scroll bars. For JavaScript, I have tried hard not to write any and so far have been successful although some of Microsoft's software writes some JavaScript for me. So, in particular, for my Web site, I still can't find a meaning of 'multi-screen' that is useful.

I'm talking about good definitions and clear communications.

So many words, so little sense.

Calm down and read it, actually read it, see the problem, which is HUGE, and begin to see the importance of the problem and the need for a good solution which is just a short lesson in Technical Writing 101.

My first post was short, but apparently was too short for everyone to 'get it'.

Apparently some people actually like in-group jargon and gibberish.

I got it, we will sort out the nomenclature

Reply on news.ycombinator.com