Getting Started with JavaScript

[mkaz]

Description

An introductory tutorial for getting started working with JavaScript and the Block Editor. A lot of the documentation is just snippets of JavaScript code assuming the developers know what to do with it. This tutorial aims to get developers who may not be familiar started off.

See #11392

I welcome any additional feedback, expanding, and building on this as a start.

Also, I am not sure how the documentation manages the multiple pages and navigation so this probably could be broken up into other pages like the block tutorial.

Online Preview: https://github.com/WordPress/gutenberg/tree/docs/11392/javascript/docs/designers-developers/developers/tutorials/javascript

[joyously]

Please use standard practices, such as a consistent prefix, and one that is not just two letters (my).
People get confused with where prefixing is needed, and why the prefix can't have a dash.

Also, please be consistent in the PHP with regard to order. Either function and then add_action, or add_action and then function, but use the same way every time. It keeps it easier to digest. I personally prefer to define the function and then add_action, but that's just how I think.

You might ought to mention the version number parameter for enqueuing scripts, but especially for styles.

This tutorial is for a script in the editor, but your style is loaded only on the front end. That will be confusing, unless your next section is about the different actions available for loading styles.

[mkaz]

@joyously Thanks for the feedback. I updated the prefix and ordering of the action/functions.

You might ought to mention the version number parameter for enqueuing scripts, but especially for styles.

I was debating how much WordPress parts to go into, I ink out to the relevant documentation for each section. It's always a hard balance to keep things brief to not overwhelm people, but also complete.

This tutorial is for a script in the editor, but your style is loaded only on the front end. That will be confusing, unless your next section is about the different actions available for loading styles.

The block style modification adds a class to blockquotes, which isn't really visisble unless you look at the source. So I thought it would be nice to be able to see it doing something, which is why I added the CSS part, not sure if that is overly confusing.

As for next part, not sure how deep to go with it, the idea was to get setup and show an example of using the documentation to apply the change. I'm all for adding to it to help users further.

[joyously]

It's always a hard balance to keep things brief to not overwhelm people

I agree, however they will be confounded when they update and don't see the change because it's cached. I've seen so many theme authors leave version numbers off and then have to field support questions about clearing cache etc. so that their updates take effect.

see it doing something, which is why I added the CSS part

It's not too confusing except that everyone always says they want the back to match the front, so why wouldn't you load the CSS in both?

[danielbachhuber]

Great start! I've left some comments and suggestions.

If you have the bandwidth, it think it'd be really worthwhile to "user test" this documentation with a layperson at WCUS. Specifically, sit them down at a laptop, have them follow the documentation, and observe their usage to see what sort of questions they run into.

[mkaz]

@danielbachhuber Thanks so much for all the feedback, I really appreciate it! I updated with your change suggestions. I'll take another pass through for the code docs and additional ideas.

If you have the bandwidth, it think it'd be really worthwhile to "user test" this documentation with a layperson at WCUS.

Good suggestion, but I'm unfortunately not at WCUS. It would be great to see someone new walk through and see what additional questions they might have. It is always tricky trying to guess where someone might get stuck.

[oandregal]

This is great work, bravo!

[oandregal]

Merging still seems to be blocked, so unsure how to go about this. cc @chrisvanpatten I'm tagging this as 4.8 in case we have to wait for landing this PR.

[gziolo]

All changes which are purely docs related should be under Documentation & Handbook milestone to simplify the process of plugin release :)

[gziolo]

@mkaz - can we cross-link tutorial steps to make navigation easier? You can either copy the table of contents or link to the next part at the end of the page.

By the way, it's a really nice idea to add this kind of tutorial. 💯

[mkaz]

@gziolo The pages will be auto linked with prev/next links at the bottom when published in the handbook. You can see the Blocks Tutorial example here

I updated the table of contents and generated the manifest which makes sure that happens.

[chrisvanpatten]

I have a partial review here. More to review, but I have other things to work on this AM and wanted to get you as much as I could quicker :)

[chrisvanpatten]

Some language tweaks! Looking good and I think it'll be an easy approval after these are resolved.

[chrisvanpatten]

SO close. Images need to be full absolute URLs, not just paths. Otherwise, looking 💯

[chrisvanpatten]

This is an awesome improvement. Thank you @mkaz!

[chrisvanpatten]

Travis is ¯_(ツ)_/¯ so I'm going to merge… thanks for working on this @mkaz!