Add gh-pages notes to readme, and rearrange for a Developer focus.

README.md

@@ -13,6 +13,58 @@ We have measured over one million unique [completions](https://twitter.com/codeo
 
 ![grid_comp](https://user-images.githubusercontent.com/2205926/165404102-87073dad-8d90-482a-ad68-bc475beb6b11.png)
 
+# Development
+
+## GitHub Pages Deployment
+
+The project automatically deploys to GitHub Pages on pushes to `main`. The deployment workflow:
+- Runs tests and builds the project (`yarn test && yarn build`)
+- Copies public assets to dist folder
+- Deploys to `gh-pages` branch using GitHub Actions
+- Publishes to https://code-dot-org.github.io/ml-activities/
+
+## Getting started
+
+Steps to get up and running:
+
+```
+git clone [email protected]:code-dot-org/ml-activities.git
+cd ml-activities
+nvm install
+nvm use
+npm install -g yarn
+yarn
+yarn start
+```
+
+At this point the app will be running at [http://localhost:8080](http://localhost:8080) with live-reloading on file changes.
+
+[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/code-dot-org/ml-activities)
+
+## Integration with local [code-dot-org repo](https://github.com/code-dot-org/code-dot-org)
+
+Similar to https://github.com/code-dot-org/dance-party, ml-activities is built from a small repo as an app which is then used by the code.org dashboard to run individual levels in a script.
+
+If you want to make changes locally in ml-activities and have them show up in your apps build, do the following:
+
+- In the ml-activities root directory `yarn link`
+- In the code-dot-org apps/ directory `yarn link @code-dot-org/ml-activities`
+This will set up a symlink in apps/node_modules/@code-dot-org to point at your local changes. Run `yarn build` in ml-activities, and then the code-dot-org apps build should pick up the changes (generated in ml-activities' `dist/`) next time it occurs (including in already-running `yarn start` build in code-dot-org).
+  - Note that ml-activities' `yarn start` can be left running when `yarn build` is run.  But a new invocation of `yarn start` will intentionally clear the `dist/` directory populated by `yarn build` to ensure we don't have outdated assets left in it.
+- If you want to go back to using the published module, in the code-dot-org apps/ directory run `yarn unlink @code-dot-org/ml-activities`.  You'll be given additional instructions on how to force the module to be rebuilt after that.
+
+## Publishing a new version
+
+First, ensure you have the `main` branch checked out locally, and that it's up to date.
+
+To publish a new version, the following command should work:
+```
+npm version 0.0.29
+```
+With `0.0.29` replaced by the new version number that should be published.
+
+Note: make sure you are logged into `npm` first.  If not, the command may fail with a misleading `E404` error.  You can see if you're logged in with `npm whoami`, and if not logged in, can can use `npm login`.
+
 # Design notes
 
 ## Modes
@@ -141,55 +193,6 @@ The full functionality of this app is enabled when hosted by https://studio.code
 
 If Google Analytics is available on the page, the app generates a synthetic page view for each scene, allowing for an understanding of usage and duration of each scene in the script.
 
-# Additional information
-
-## Common operations
-
-The documentation for common operations for **AI Lab** is comprehensive and should apply to this project too: https://github.com/code-dot-org/ml-playground#common-operations
-
-
-## Getting started
-
-Steps to get up and running:
-
-```
-git clone [email protected]:code-dot-org/ml-activities.git
-cd ml-activities
-nvm install
-nvm use
-npm install -g yarn
-yarn
-yarn start
-```
-
-At this point the app will be running at [http://localhost:8080](http://localhost:8080) with live-reloading on file changes.
-
-[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/code-dot-org/ml-activities)
-
-### Integration with local [code-dot-org repo](https://github.com/code-dot-org/code-dot-org)
-
-Similar to https://github.com/code-dot-org/dance-party, ml-activities is built from a small repo as an app which is then used by the code.org dashboard to run individual levels in a script.
-
-If you want to make changes locally in ml-activities and have them show up in your apps build, do the following:
-
-- In the ml-activities root directory `yarn link`
-- In the code-dot-org apps/ directory `yarn link @code-dot-org/ml-activities`
-This will set up a symlink in apps/node_modules/@code-dot-org to point at your local changes. Run `yarn build` in ml-activities, and then the code-dot-org apps build should pick up the changes (generated in ml-activities' `dist/`) next time it occurs (including in already-running `yarn start` build in code-dot-org).
-  - Note that ml-activities' `yarn start` can be left running when `yarn build` is run.  But a new invocation of `yarn start` will intentionally clear the `dist/` directory populated by `yarn build` to ensure we don't have outdated assets left in it.
-- If you want to go back to using the published module, in the code-dot-org apps/ directory run `yarn unlink @code-dot-org/ml-activities`.  You'll be given additional instructions on how to force the module to be rebuilt after that.
-
-### Publishing a new version
-
-First, ensure you have the `main` branch checked out locally, and that it's up to date.
-
-To publish a new version, the following command should work:
-```
-npm version 0.0.29
-```
-With `0.0.29` replaced by the new version number that should be published.
-
-Note: make sure you are logged into `npm` first.  If not, the command may fail with a misleading `E404` error.  You can see if you're logged in with `npm whoami`, and if not logged in, can can use `npm login`.
-
 ## Adding new fish components
 All fish components live in `public/images/fish` in their respective folders (eg bodies live in `body/`). Despite the fact that the fish face right in most of the tutorial, they are built as if they face left in order to simplify the math for the anchor points. This means that all components should be oriented as if the fish is facing left, which might require flopping any new assets. After adding the assets, they will need to be added to `src/utils/fishData.js`. `bin/determineKnnData.js` will output some of the lines that will be needed in `fishData`.
 
@@ -203,7 +206,7 @@ Bodies need an anchor point for the body then all of the other components, relat
 ### Dorsal fin
 Some dorsal fins define an x-adjustment to shift the anchor point. This is useful for dorsal fins that might look odd is not positioned correctly (eg symmetical).
 
-## I18n
+## Internationalization (I18n)
 By default, this tutorial is in English. The strings live at i18n/oceans.json and should not be moved without corresponding changes to the I18n pipeline in `code-dot-org`. Translations can be passed into the app using the `i18n` param. If any translations are missing, the English string will be used as a default. This also means that adding a new string is safe and does not require any further steps.
 
 ## Machine Learning algorithms