[WA]

The graphics are nice, but I think you can polish the writing.

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:

> The purpose of HTML, CSS, and JavaScript, the difference between frameworks and languages, and finding your way around a basic website project with Atom.

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 [1]. 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.

[1] https://material.io/guidelines/style/writing.html

[mcintyre1994]

To add on to point 1 here, those sentence fragments should be links (and visually distinguished as them). Currently they're not, there's just the read more link - and if you go there and ctrl-f for any of the fragments (say "purpose", "frameworks and" or "basic website" you'll get nothing. So it's impossible to go from "that part of that chapter sounds good" to reading about it unless you know enough about the topic to ctrl-f a different term.

[morganvachon]

> 2. Simplify sentences. Cut adjectives. Shorten. It reads academic.

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.

[WA]

Personality and friendliness don't come from unnecessary words. A book should be written with authority and emphasize with the reader. Some parts of the text do this well, such as this:

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

[JackFr]

You should empathize with the reader.

[lucideer]

The reader appreciates a readable text. Empathise and provide that.

[WA]

Oh yeah, thanks for pointing out the typo. Too late to fix it.

[bshimmin]

Or write in a way that's light, friendly, and engaging. Not everyone wants something that's "fast and efficient" and information-dense, perhaps especially not people taking a beginner's course on HTML and CSS.

[wruza]

That's how I filter out turorials. If it is not fast and efficient, or involves weak analogies and too playful with terms, then I simply skip them until one is really factful, concise and to the point.

I am noob, not stupid.

Edit: typo

[Jemmeh]

It really just depends on the person. I have a few tutorial videos up on Youtube, and it's pretty 50/50 on the comments being "this is too fast" and "thanks for not rambling, slow tutorials are annoying".

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.

[lucideer]

YouTube is really a very different case, and in fact the opposite is the case for text.

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.

[Jemmeh]

You make a good point and I see where you're coming from. But I've gone through a few text tutorials that just fly through the topics without going into enough depth or examples. I think if you're fairly advanced in a skill, sometimes it's hard to relate to the mindset of someone who is new to it. Like, oh, this is so easy to me, I only need one sentence to explain it. But really it needs a whole paragraph.

It's all a balancing act of course. Like you said, has to be both clear and fast.

[wruza]

Otoh, after reading two chapters it seems that this turorial does not involve that. It is pretty good and thorough for complete beginners.

[hbharadwaj]

Are there guides similar to Material Design that you would recommend to an app developer? Looking for Dos and Don'ts. Appreciate any help in this direction!

[WA]

Don't overthink it. The material design guidelines teach you what to look out for. The book On Writing Well helps. But most rules are simple enough: Write in the active voice, cut unnecessary words, write, then edit and revise. It's a process, it needs practice, too ;)