
Web Fundamentals: A handbook for best practices - isopod
https://developers.google.com/web/fundamentals/
======
aresant
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...](https://developers.google.com/web/fundamentals/documentation/user-
input/index) \- 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...](https://developers.google.com/web/fundamentals/documentation/user-
input/index") \- 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...](https://developers.google.com/web/fundamentals/resources/styleguide/markdown-
guide)

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 . . .

~~~
kinlan
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.]

~~~
aresant
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/](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.

~~~
kinlan
:) 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.

------
yaix
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.

~~~
maxhe
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](https://github.com/google/WebFundamentals/issues/1)

>headlines/h2s

[https://github.com/google/WebFundamentals/issues/52](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...](https://developers.google.com/web/fundamentals/documentation/multi-
device-layouts/rwd-fundamentals/index)

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](https://github.com/google/WebFundamentals/issues/new)

------
ispivey
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?

~~~
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.

------
Braunbart
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](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...](https://web-
central.appspot.com/web/essentials/icons/icons.woff). This can be fixed by
moving the resource to the same domain or enabling CORS.

~~~
kinlan
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.

------
dman
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?

~~~
kinlan
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](https://github.com/google/WebFundamentals/issues/14)).

~~~
traek
For issue 14, I believe he meant that the image on the page
([https://developers.google.com/web/fundamentals/documentation...](https://developers.google.com/web/fundamentals/documentation/performance/critical-
rendering-path/images/progressive-rendering.png)) shows the optimized
rendering taking 1.5 seconds, not that the page itself loads in 1.5 seconds.

------
kinlan
Repository for filing issues:
[https://github.com/google/WebFundamentals/issues](https://github.com/google/WebFundamentals/issues)

------
taternuts
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!

~~~
atom-morgan
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.

------
turar
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?

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

~~~
gesman
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.

~~~
phaer
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.

------
snomad
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.

------
untilHellbanned
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.

------
coreymgilmore
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.

~~~
kinlan
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](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.

------
theycallmemorty
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!

------
userbinator
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.

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

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

------
contingencies
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.

~~~
tragic
> (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.

------
carrotleads
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.

------
skeletonjelly
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?

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

~~~
maxhe
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](https://github.com/google/WebFundamentals/issues/new)

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

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

~~~
maxhe
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).

------
auvrw
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 迹?

------
dvfurlong
There are errors in this.

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

------
felipesabino
why no +1 button?

~~~
owenversteeg
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.

------
graycat
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.

~~~
kinlan
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/17)
[https://github.com/google/WebFundamentals/issues/18](https://github.com/google/WebFundamentals/issues/18)

~~~
graycat
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.

~~~
BasDirks
So many words, so little sense.

~~~
graycat
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.

~~~
kinlan
I got it, we will sort out the nomenclature

