1. It took me probably 30 seconds to understand that the text blocks on the start page are summaries of what's in every chapter. Try to read this without knowing that this website is an online book:
This doesn't make any sense if you don't know that it describes a chapter in a book.
2. Simplify sentences. Cut adjectives. Shorten. It reads academic. Examples:
> Our goal is to make it as easy as possible for complete beginners to become professional web developers, so if you’ve never written a line of HTML or CSS, but you’re contemplating a career shift, grab a cup of coffee, take a seat, and let’s get to work.
This is a single sentence. It's hard to understand. Your readers aren't all native Americans. This could be turned into:
-> This guide helps you to become a professional web developer, even if you've never written a single line of HTML or CSS.
> They’re very closely related, but they’re also designed for very specific tasks. Understanding how they interact will go a long way towards becoming a web developer.
Ctrl + F "very": Too often.
A good editor might reduce the text by 25-50%. My secret tip is the Material Design Writing guide . It shows how to write for apps. With apps, the user needs to get a task done as fast and efficient as possible. Write that way.
You bring up some valid issues, but I think you're missing the point of the guide: To be friendly. It has a few parts that could use some editing but overall it feels friendly and interactive. Some of the changes you suggest make it seem cold and boring, which (to me at least) would be a reason to put it down and never pick it back up.
> Learning HTML and CSS is hard, but it doesn’t have to be.
That's a great start. It's friendly and it doesn't have unnecessary words in it. It's actually quite powerful.
There's a fine line between being friendly and starting to babble.
I am noob, not stupid.
I think in general someone this new to programming concepts would probably want something a little slower. Once you get the main concepts down for programming then you can speed up, but the abstract thinking is hard for a lot of people to wrap their head around at first.
For speech, the speaker sets the pace, so the challenge of accessibility is actually twofold: the speaker needs to both be clear and not too fast (or too "efficient").
In text, it's the opposite: the reader sets the pace, so more efficient writing will make reading (at whatever pace) less taxing.
It's all a balancing act of course. Like you said, has to be both clear and fast.
The only comments I have is that it's technically "web design" rather than "web development", and there's nothing about taking the work the user has done and putting it on a server somewhere so other people can see it. It'd be a shame for someone to work through the whole thing and not have a working website at the end.
And I am not talking about using different frameworks / compiled languages / etc... I'm talking about the improved techniques we've developed over the years combined with new features in browsers, such as:
* HTML5 vs. HTML4 (streamlined and more consistent syntax in a lot of places)
* Float-based grid systems for layout
* Flexbox(!) for alignment
* media queries and picture/srcset for responsive design (heck, the whole concept of responsive design)
* web fonts (not being limited to the dozen or so that are available through the OS only)
* BEM methodology (having a modular mindset about styling components, combined with avoiding specificity issues by just using a class for everything)
Why are you assuming said website needs to be successful on the market? Maybe it's a personal website or a hobby project.
If I were starting now, my inspiration would possibly be things like: responsive, single-page apps, with ajax, websockets, etc.
I was going everywhere and viewing source and you could basically figure out how everything was made. Now--not so much.
It's not so much 'success' as similarity with popular projects.
(Pleasantly surprised to see this is still going strong after 20+ years.)
I recently taught some "intro to web design / development" classes to college students (mostly designers, so coming to it more from a creative perspective as opposed to "coders at heart"), and this is the "textbook" I wish I had had then! The order that concepts are introduced is perfect, and I think the decisions made about what to explain vs. what to ignore are spot on.
When I got to the part with hr and br tags, I was thinking to myself "tsk tsk, the closing slashes are unnecessary"... then the next paragraph explains how they're unnecessary but the rationale for using them is a good idea (in the context of learning).
I also very much appreciate that it's strictly HTML and CSS and doesn't start off with all the extra mental overhead of build tools, compiled languages, server setups, etc.
Really well done!
The last time I built a web page was probably 2001 and the fanciest it got was frames in Frontpage. Prior to that it was all html in notepad. I do not program.
I am however, trying to get a website up for a new education venture I'm building. I'm using a Bootstrap framework. There's enough old stuff in there that I can figure out how to edit it, but also enough new stuff to throw me for some loops. A lot of the tutorials I've found to explain elements are either too simple or too complex.
Your tutorial seems to be the sweet spot. I flipped to the part about responsive images and it answered some previously unanswered questions I harbored.
When this post hit HN awhile back I got excited by the template but I couldn't figure out how to edit important parts of it because it used SVG images. I didn't know what SVG was or if/how to edit/replace them. Your tutorial is the first simple explanation I've seen regarding SVGs and their place/purpose in the responsive image landscape.
Much appreciated as skimming your site has already been helpful.
In fact I have such one "scratchpad" crammed into data:uri and bookmarked and keep regularly using it to quick test almost anything HTML / CSS / XML / SVG / JS related. (I am coder.)
>HTML is for adding meaning to raw content by marking it up.
HTML is the frame of the house.
>CSS is for formatting that marked up content.
CSS is the interior and exterior design of the house that's intertwined with the HTML framework.
I think graphical content that reinforces the above analogies would go a long way in helping newcomers to more quickly understand and remember the basic concepts.
This was, because answers often involved adding some overbloated framework to my homepage that was supposed to solve all problems.
After two days of googling arround I arrived at very simple HTML + CSS, like you are describing, and did not need kilobytes of "CSS frameworks".
Whenever I see these I wonder if they remembered to take someone with no subject matter knowledge and have them attempt to go through it.
For all I know this site did. I'm just musing out loud,
What's hard is being able to teach any single person them – that requires many sorts of people skills. The irony is that for people with the right mindset, learning the 3 of them, or programming in general is one of the easiest thing they could do.
But try teaching this stuff to people with no experience, and/or people who don't have as analytical a mind as us tech folks and you will quickly discover just how hard it can be.
(I recently taught a college class that was an intro to web design / development - suffice to say it really gave me a clearer picture of how far I'd come in my own professional skills over the years... it's easy to forget what it was like before you knew what you know now :)
My biggest nightmare is trying to learn another language, I took 7 years of Spanish in school and I literally can't speak a sentence of Spanish.
Prepare people for what's ahead.
Just a few examples to demonstrate what I mean:
- Grey-on-white color scheme: high brightness, leading to eye strain.
- Font sizes and div widths are set in pixels.
- Fails validator.w3.org validation.
- Light-grey-on-white navigation links: low contrast, leading to barely legible text.