Suggestion: introduction block

[jdhartley]

Hey Ben, this was an amazing read, and thank you for sharing.

A few others have already raised this point, and I wanted to open a separate issue and share my concern too: The phrasing and format of this document comes across as "The Right" way to do things (// bad vs // good).

A new, fresh front-end developer that might come across this will learn some great stuff and also debatable opinions. A lot of these examples are not necessarily the "best practices for maximum browser support" and most of it is fluctuating technology.

You've expressed in #4 that you won't have time to explain in each and every block why you personally chose this style, so I would suggest just a simple introduction/note right at the top under your heading, simply stating these are opinions and suggestions.

[cdl]

I agree with this - explaining "why" is key when it comes to resources that are meant to be learnt from. If this isn't feasible, you should probably include a notice stating that these are merely suggestions based on personal opinions, and these guidelines are not intended to be a definitive guide to good practice, nor something that beginners should be learning from.

[AsifMushtaq]

I also agree with above suggestion. We have a very good example of John Papa's AngularJs Style guide which explain his relational behind every given style guideline.

[conwaydev]

I definitely agree with this suggestion, I feel like a lot of developers can easily become dissuaded by the advice that you're giving without proper context of why these are good decisions or proper guidelines.

[danzimm]

I just want to comment - I am a new web developer of sorts, and read this. I was in fact quite dissuaded by several things as @conwaydev suggested might be the case.

[aweary]

It'd be wise to specify who your audience is as well. As mentioned in #26 the Javascript section uses ES6 features that aren't going to be available unless you use a transpiler. It's a valid argument that ES6 is the future of Javascript and should be used when possible, but I don't think it's safe to assume that the average beginner is going to be as comfortable understanding ES5 vs ES6, the current state of browser implementations, why a transpilier is needed at the moment, etc.

The guide covers some really basic front-end concepts in CSS/HTML yet you're assuming a lot of the reader here when it comes to Javascript. It just doesn't seem like its being consistent with its expectations of the reader.

The best option, I'd say, is to create an introduction explaining the target audience and expected level of competence. Outline which features here are non-standard within the current browser environment (this is a front-end guide after all, not a guide on the current Javascript standard) and how they can be used now via something like Babel.

[prayerslayer]

I agree with all previous commenters and think a disclaimer of sorts should be mandatory.

Your points make sense to an experienced developer. Or at least she will understand what your tradeoffs are. To a new developer some points probably seem arbitrary, ie.

Avoid animating other properties than opacity and transform.

Why? What's wrong with color? Why is margin-left bad and translateX good?

[bendc]

@prayerslayer Because opacity and transform are the only properties fast to animate.

Closing this issue but keeping this suggestion in mind :)