readme: simplify getting started section for users new to JS

README.md

@@ -1,24 +1,28 @@
 
-## twinkle-starter
+# twinkle-starter
 
 This is a template repository to create a Twinkle customisation for a new wiki. 
 
-To use this template, click on the ![Use this template](https://user-images.githubusercontent.com/6702424/98155461-92395e80-1ed6-11eb-93b2-98c64453043f.png) button near the top. The [template initialisation workflow](https://github.com/wikimedia-gadgets/twinkle-starter/blob/master/.github/workflows/template_initialization.yaml) will shortly create a new commit in your repository replacing the placeholders in the package.json file. If you don't wish to use GitHub, please see [the note below](#user-content-use-a-source-code-host-other-than-github).
+## Getting Started
+You need to have the following installed on your system: (i) [Git](https://git-scm.com/downloads), (ii) [Node.js](https://nodejs.org/en/download/) v13 or above, (iii) npm – though this usually comes along with Node.js. You'll also need to have some basic JavaScript familiarity. 
 
-Add the [topic "wikimedia-twinkle"](https://github.com/topics/wikimedia-twinkle) to your GitHub repository so that it is easy for others to locate all twinkle repos.
+- To use this template, click on the ![Use this template](https://user-images.githubusercontent.com/6702424/98155461-92395e80-1ed6-11eb-93b2-98c64453043f.png) button near the top (don't clone this repo). Give your repo a suitable name, such as "twinlke-frwiki" if it is for the French Wikipedia. The [template initialisation workflow](https://github.com/wikimedia-gadgets/twinkle-starter/blob/master/.github/workflows/template_initialization.yaml) will shortly create a new commit in your repository replacing the placeholders in the package.json file. Add the [topic "wikimedia-twinkle"](https://github.com/topics/wikimedia-twinkle) to your GitHub repository so that it is easy for others to locate all twinkle repos. If you don't wish to use GitHub, please see [the note below](#user-content-use-a-source-code-host-other-than-github).
 
-### Customising Twinkle - Getting Started
-You need to have the following installed on your system: (i) Git, (ii) Node.js v13 or above, (iii) npm.
-
-After cloning the repo generated by this template, run `npm install`. If `npm install` doesn't work and you're using npm v7, try `npm install --legacy-peer-deps`. 
+- Clone the generated repo: (remember to replace "twinkle-frwiki" in the commands with the actual name of your repository!) 
+```bash
+git clone https://github.com/wikimedia-gadgets/twinkle-frwiki.git
+cd twinkle-frwiki
+```
 
-This repo contains has all the dependencies and build tool configurations present so that you don't have to bother with them. The most significant dependency is [**twinkle-core**](https://github.com/wikimedia-gadgets/twinkle-core) which provides all the core functionality on top of which you can write your customisations and extensions. There exists automatically generated **[Code Documentation for twinkle-core](https://tools-static.wmflabs.org/twinkle/core-docs/modules.html)** which provides details on functioning of its various modules.
+- Now, run `npm install`. If `npm install` doesn't work and you're using npm v7, try `npm install --legacy-peer-deps`. 
+- Add code for registering the customisations/localisations needed for your wiki (see sections below). You can test your changes as you go with `npm start`. See details in [Development section below](#user-content-development). This is the longest step in the workflow.
+- When you're done, use the `grunt build` command to generate files that you can actually copy over to the wiki (see [Deployment section below](#user-content-deployment) for details). 
 
-Twinkle-core uses [TypeScript](https://www.typescriptlang.org/) - a compiled superset of JavaScript that makes it easier to write bug-free applications. You can choose to write your customisations in either JavaScript or TypeScript. However, using JavaScript sidesteps all the type-safety features built into twinkle-core, which may make it harder to debug. If you are new to TypeScript, refer to the [official documentation's introduction for JS programmers](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html).
+This repo contains has all the dependencies and build tool configurations present so that you don't have to bother with them. The most significant dependency is [**twinkle-core**](https://github.com/wikimedia-gadgets/twinkle-core) which provides all the core functionality on top of which you can write your customisations and extensions. There exists automatically generated **[Code Documentation for twinkle-core](https://tools-static.wmflabs.org/twinkle/core-docs)** which provides details on functioning of its various modules.
 
-Webpack is used to "bundle" all the code (including dependencies) into a single bundle – which you can upload to the wiki (see [Deployment section](#user-content-deployment)). 
+Twinkle-core uses [TypeScript](https://www.typescriptlang.org/) – a compiled superset of JavaScript that makes it easier to write bug-free applications. You can choose to write your customisations in either JavaScript or TypeScript. However, using JavaScript files causes all type-safety features built into twinkle-core to be side-stepped, which may make it harder to debug. Since TypeScript is a superset of JavaScript, all JS code is also valid TS code; as such you can write JS code in TS files – this should still make it easier to catch errors. If you are new to TypeScript, refer to the [official documentation's introduction for JS programmers](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html).
 
-### File structure
+All code is written in the form of [ECMAScript modules](https://webpack.js.org/guides/ecma-script-modules/). Webpack is used to "bundle" all the code (including dependencies) into a single file – which you can upload to the wiki (see [Deployment section](#user-content-deployment)). 
 
 ### twinkle.ts 
 `twinkle.ts` file is the entry point. Specify all site-specific configurations here. The list of module classes is also put here.
@@ -42,7 +46,6 @@ Refer to the documentation of each module for guidance on configuring them. Fluf
 Each module in Twinkle extends the abstract class [TwinkleModule](https://twinkle.toolforge.org/core-docs/classes/twinklemodule.html). Some core module classes are also abstract, indicating they don't work by themselves and must be extended with the specified abstract fields or methods that you have to provide.  
 
 Customisation written for English Wikipedia at [wikimedia-gadgets/twinkle-enwiki](https://github.com/wikimedia-gadgets/twinkle-enwiki) can be used as a reference.
-
 
 ### Creating your own modules
 Apart from extending the core module, you can also create your own modules customised to the needs of your wiki. In general, a Twinkle module is structured as follows:
@@ -70,6 +73,12 @@ class MyCustomModule extends TwinkleModule {
 }
 ```
 
+### Twinkle-core message translations
+Twinkle-core uses Translatewiki.net for message translations. Check if its messages are available in your wiki's language (https://github.com/wikimedia-gadgets/twinkle-core/tree/master/i18n). For messages that aren't available:
+* Consider contributing the translations directly to translatewiki.net – these messages will be used by all twinkle installations in that language
+* If you can't contribute to translatewiki.net or if there are any messages that you want to be project-specific rather than language-specific, then define them in the `src/messages.json` file. Any messages in this file will override messages coming from translatewiki.net.
+
+
 ## Development
 
 Firstly, you'll want to make sure your editor is properly configured to work with TypeScript. For example, you may need to install a plugin (such as atom-typescript if you use atom editor), in order to fully take advantage of TypeScript. If you use VS Code, TypeScript support is built-in, so no extensions are required.
@@ -78,11 +87,6 @@ Commands:
 - `npm start` - this creates a quick build of the project which you can test by loading `mw.loader.load('http://localhost:5500/twinkle.js');` from your on-wiki common.js page (or from the browser console). 
 - `grunt build` - this creates a minified single-file build that you copy over to the wiki (see Deployment below).
 
-### Twinkle-core message translations
-Twinkle-core uses Translatewiki.net for message translations. Check if its messages are available in your wiki's language (https://github.com/wikimedia-gadgets/twinkle-core/tree/master/i18n). For messages that aren't available:
-* Consider contributing the translations directly to translatewiki.net – these messages will be used by all twinkle installations in that language 
-* If you can't contribute to translatewiki.net or if there are any messages that you want to be project-specific rather than language-specific, then define them in the `src/messages.json` file. Any messages in this file will override messages coming from translatewiki.net.
-
 ### Browser compatibility
 Twinkle-core is compatible with all browsers for which MediaWiki provides JavaScript support, including IE 11. However, in your own customisations, you can choose to [avoid IE11 support](https://www.mediawiki.org/wiki/Compatibility/IE11) unless you have good reason to support IE. Do check MDN docs or [caniuse.com](https://caniuse.com/) before using modern browser APIs to ensure that they're supported in most browsers.
 
@@ -125,20 +129,20 @@ Create a central loader (say [[User:Example/twinkle.js]]):
 ```js
 mw.loader.using([
 	'mediawiki.user', 'mediawiki.util', 'mediawiki.Title', 'mediawiki.api', 
-    'mediawiki.libs.pluralruleparser', 'es6-promise'
+	'mediawiki.libs.pluralruleparser', 'es6-promise'
 ]).then(function () {
 	function load(pageName, css) {
 		return mw.loader.getScript(
 			'/w/index.php?title=User:Example' + pageName + '&action=raw&ctype=text/' + (css ? 'css' : 'javascript'), 
-            css ? 'text/css' : null  
+			css ? 'text/css' : null  
         );
-    }
-    mw.loader.load('jquery.ui');
-	
-    // Morebits needs to be available for twinkle.js to parse
+	}
+	mw.loader.load('jquery.ui');
+
+	// Morebits needs to be available for twinkle.js to parse
 	load('twinkle/morebits.js').then(function() {
 		load('twinkle/twinkle.js');
-    });
+	});
 	load('twinkle/select2.js');
 	load('twinkle/twinkle.css', true);
 	load('twinkle/morebits.css', true);