docs: reorganize contribute to blockly docs

packages/docs/docs/guides/contribute/core/building.mdx → packages/docs/docs/guides/contribute/core/building_and_compilation/building.mdx

@@ -8,7 +8,7 @@ image: images/blockly_banner.png
 
 :::warning
 Unless you are modifying the Blockly source code directly, you probably
-don't need to build Blockly run any of the scripts documented below yourself.
+don't need to build Blockly or run any of the scripts documented below yourself.
 Instead, follow the instructions in [the "Get the Code"
 section](/guides/get-started/get-the-code#get-the-code-1) of the [Get Started](/guides/get-started/get-the-code) page to install [the `blockly` NPM package](https://www.npmjs.com/package/blockly) or download the `.tgz` file attached to
 [the latest release on GitHub](https://github.com/RaspberryPiFoundation/blockly/releases/latest).

packages/docs/docs/guides/contribute/core/core-architecture/core-tour.mdx

@@ -0,0 +1,134 @@
+---
+description: Overview of the structure and architecture of the core repository.
+title: Core Tour
+image: images/blockly_banner.png
+---
+
+# Core tour
+
+## Blockly code
+
+The code for Blockly can be found on
+[GitHub](https://github.com/RaspberryPiFoundation/blockly/tree/main). This
+page is intended as a guide so that you can explore Blockly's repository and
+determine where to start if you're working on a GitHub issue. 
+
+If you would like to learn more about Blockly's code, you can do the following: 
+- Read this document
+- Click through the code on [GitHub](https://github.com/RaspberryPiFoundation/blockly/tree/main)
+- Consult the [API documentation](/reference/blockly/)
+
+:::tip 
+Don't worry, you do **not** have to read and understand every piece of Blockly's 
+code in order to contribute to Blockly! You just need to understand the parts
+that relate to what you're working on. 
+:::
+
+### Folder structure
+
+The root folder of Blockly's repository contains many files (and some folders) 
+for the configuration of our
+[development tools](/guides/contribute/core/development_tools).
+
+Blockly's source code is located in `packages/blockly`. As an external 
+contributor, you will likely focus on the files in the `core/` and `tests/` 
+folders, but all of the folders are listed below.
+
+`packages/blockly/`
+- `blocks/` - Block definitions for built-in blocks
+- `core/`
+  - `bubbles/` - Code for creating popover bubbles, such as mutator UI
+  - `clipboard/` - [Copy/paste](/guides/configure/copy-paste/) logic
+  - `comments/` - Workspace [comments](/guides/configure/) and block comments
+  - `dragging/` - Mechanics for
+    [dragging objects](/guides/configure/dragging/draggable/) in the workspace
+  - `events/` - [Events](/guides/configure/events) class and built-in events
+  - `icons/` - [Icon](/guides/create-custom-blocks/icons/overview/) class and
+    built-in icons
+  - `inputs/` -
+    [Input](/guides/create-custom-blocks/inputs/creating-custom-inputs/) types
+    and their connections
+  - `interfaces/` - Shared interfaces implemented across core
+  - `keyboard_nav/` - [Keyboard navigation](/guides/configure/keyboard-nav/)
+    - `navigation_policies/` - Engines that decide where keyboard focus moves
+    - `navigators/` - Per-element rules telling the navigator where an element's 
+    neighbors are
+  - `renderers/` - Default
+    [renderers](/guides/create-custom-blocks/renderers/overview/)
+    - `common/` - Base classes shared by the renderers
+    - `geras/` - Built-in renderer with 3-D edges
+    - `measurables/` - Classes that represent each part of a block
+    - `thrasos/` - Built-in minimalist renderer, Blockly default
+    - `zelos/` - Built-in renderer with rounded blocks
+  - `serialization/` - [Saving and loading](/guides/configure/serialization/)
+    workspace state
+  - `theme/` - Built-in [themes](/guides/configure/appearance/themes/)
+  - `toolbox/` - The [toolbox](/guides/configure/toolboxes/toolbox/)
+  - `utils/` - Utility functions used throughout core
+- `demos/` - Some deprecated Blockly demos. Up-to-date demos and examples are in [blockly-samples](https://github.com/raspberrypifoundation/blockly-samples).
+- `generators/` -
+  [Code generators](/guides/create-custom-blocks/code-generation/overview/) for
+  the built-in languages
+- `media/` - Sound effects, cursors, etc.
+- `msg/` - Translated [message strings](/guides/configure/translations/)
+- `scripts/` - Scripts for building, packaging, and maintaining Blockly.
+- `tests/` - [Unit tests](/guides/contribute/core/testing/unit_testing)
+- `typings/` - Supplemental hand-written type declarations
+
+### Core files
+
+There are many files in `core/` that don't live in a subfolder, for various 
+reasons. If you're making a change to Blockly, you should take a look at these 
+files, as well as the subfolders in `core/`, to find the relevant code.
+
+Note that Blockly's foundational base classes, like `Block`, `Workspace`, and
+`Connection` are located in the `core/` folder, outside of any subfolders.
+
+## Blockly docs
+
+Blockly's documentation is located in `packages/docs`.
+
+As an external contributor, you will likely focus on the files in the `docs/`
+and `static/` folders, but all of the folders are listed below.
+
+`packages/docs/`
+- `docs/` - The documentation content itself, written in Markdown/MDX
+  - `codelabs/` - Step-by-step tutorials
+  - `guides/` - Topic-based how-to guides
+  - `publications/` - Academic papers and talks about Blockly
+  - `reference/` - Generated [API reference](#api-documentation)
+- `src/` - Source code for the Docusaurus site
+  - `components/` - Custom React components used in the docs
+  - `css/` - Custom styles
+  - `pages/` - Standalone pages outside the docs content
+  - `theme/` - Docusaurus theme overrides
+  - `utils/` - Utilities for website analytics
+- `static/` - Static assets (images, redirects, etc.)
+
+### API documentation
+
+Blockly also offers [API reference documentation](/reference/blockly) that
+details the public API code. The API docs are automatically generated from the
+code itself, so they are another great resource for understanding Blockly's
+code.
+
+## Model vs. view
+
+Before digging into `core/`, it's worth understanding one key part of Blockly's 
+architecture: Blockly separates data modeling from rendering. In practice, this 
+means that some parts of Blockly have two classes that represent them: one for 
+the data model, and one for the rendered version.
+
+For an example, look at the implementation of blocks. In the `core/` folder, 
+there are two files that implement blocks: `block.ts` and `block_svg.ts`.
+
+In `block.ts`, the `Block` parent class has functions to handle data associated 
+with that block and how it behaves. There are functions in the `Block` class 
+that do deal with visual aspects of a block, like `setColour`. If you look 
+closely at `setColour` in the `Block` class, you'll see that `setColour` just 
+saves the colour. It does not render or display that colour. 
+
+`block_svg.ts`, on the other hand, creates a `BlockSvg` class that extends the 
+`Block` class to add render management. The `setColour` override in BlockSvg 
+calls the super (which saves the colour) and also *applies* that colour
+to the rendered block.

packages/docs/docs/guides/contribute/get-started/development_tools.mdx → packages/docs/docs/guides/contribute/core/development_tools.mdx

@@ -14,22 +14,6 @@ We use many of these tools through scripts. You may not need to ever run
 them directly. Knowing the names may still be helpful for debugging or filing
 issues or feature requests.
 
-### Git
-
-[Git](https://git-scm.com/) is a version control system that we use to track and
-manage changes to files.
-
-### GitHub
-
-[GitHub](https://github.com/) is a hosting platform for version control,
-collaboration, and distribution of open-source code. Git tracks the files;
-GitHub provides smooth interfaces for reviewing code, tracking issues, and
-viewing change history.
-
-**Getting started**: If you're new to Git and GitHub, work through GitHub's
-[quickstart](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/quickstart)
-tutorials to get comfortable with the basics.
-
 ### Node
 
 [Node.js](https://nodejs.org/) is a way to run JavaScript on the server (rather

packages/docs/docs/guides/contribute/core/index.mdx

@@ -17,8 +17,7 @@ to create a PR.
 - The working branch is **main** and all PRs should be made against
   main.
 - You must fill out the pull request template with the requested information.
-- Code must conform to Google's [TypeScript Style
-  Guide](https://google.github.io/styleguide/tsguide.html).
+- Code must conform to Blockly's [style guide](style_guide)
 - Use [conventional commits](/guides/contribute/get-started/commits)
   in your commit messages and pull request titles.
 - User-visible strings must be in the `/msg/messages.js` file so they may be

packages/docs/docs/guides/contribute/core/add_localization_token.mdx → packages/docs/docs/guides/contribute/core/localization_and_translation.mdx

@@ -3,13 +3,19 @@ description: How to add a new localization token to Blockly core.
 title: Add a new localization token to Blockly core
 image: images/blockly_banner.png
 ---
+# Localization and translation
 
-# Add a new localization token to Blockly core
+Blockly uses a localization system to translate user-visible text into a variety
+of languages. If you add a feature to Blockly core that requires new
+user-visible strings, you must add those strings to the message file so that
+they can be [translated by Translatewiki](#translatewiki). For information about 
+adding localization tokens for your _own_ application, see 
+[Localization][localization].
 
-If you add a feature to Blockly core that requires new user-visible strings, you
-must add those strings to `Blockly.Msg` so that they can be [translated by
-Translatewiki][translatewiki]. (For information about adding localization tokens
-for your own application, see [Localization][localization].)
+## Add a new localization token to Blockly core
+
+New user-visible strings must be added to `Blockly.Msg`. Follow 
+these steps to ensure that the new strings can be properly translated:
 
 1.  Add your new string with an appropriate name and description to the
     `msg/messages.js` file.
@@ -51,7 +57,7 @@ and in `msg/qqq.json`:
 
 Then you can reference this string in code with `Blockly.Msg['MY_NEW_MESSAGE']`.
 
-## Translation hints
+### Translation hints
 
 The triple-slash comment in `msg/messages.js` is shown to TranslateWiki users as
 supplementary information when translating. Provide context for where the
@@ -72,7 +78,7 @@ provides a link to more information.
 Blockly.Msg.CONTROLS_FOR_TITLE = 'count with %1 from %2 to %3 by %4';
 ```
 
-### Context types
+#### Context types
 
 Many of the hints use a prefix to explain the context of a message. The common
 prefixes include:
@@ -87,7 +93,7 @@ prefixes include:
 
 If your message appears in one of these context, use the appropriate prefix.
 
-## Synonyms
+### Synonyms
 
 Sometimes a message key needs to be changed, but the translations don't. In that
 case, you can set the old message as a synonym of the new message, like so:
@@ -97,7 +103,7 @@ case, you can set the old message as a synonym of the new message, like so:
 Blockly.Msg.CONTROLS_FOR_INPUT_DO = Blockly.Msg.CONTROLS_REPEAT_INPUT_DO;
 ```
 
-## Optional messages
+### Optional messages
 
 Some message strings are unlikely to need translation except in certain
 circumstances, for example, proper nouns or symbols. In Blockly, help URLs are
@@ -114,7 +120,7 @@ complete the optional translations.
 Blockly.Msg.MATH_ADDITION_SYMBOL = '+';
 ```
 
-## Notranslate items
+### Notranslate items
 
 The colours used for default block categories are marked `{{notranslate}}`. These colours are not intended to be
 localized, but are in the localization system so that developers can easily
@@ -133,3 +139,78 @@ Blockly.Msg.LOGIC_HUE = '210';
 [translatewiki]: /guides/contribute/core/translating
 [localization]: /guides/configure/translations
 [block-colour]: /guides/configure/appearance/block-colour#set-block-colour
+
+# Translate text
+
+Students shouldn't have to struggle with learning English at the same time as
+they're learning computer science concepts. If you are a native speaker of a
+language other than English, we'd appreciate your assistance in reaching the 95%
+of the world that doesn't speak English natively.
+
+## Translatewiki
+
+Translations for Blockly are handled by Translatewiki.
+
+1.  Sign up to become a translator at
+    [translatewiki.net](https://translatewiki.net/).
+1.  Do some [test
+    translations](https://translatewiki.net/wiki/Special:TranslationStash) to
+    get permission to translate (choose a language in the upper-right).
+1.  Briefly read over the [style
+    guide](https://translatewiki.net/wiki/Translating:Blockly) for Blockly's
+    translations.
+1.  Go to Blockly's [message group](https://translatewiki.net/w/i.php?title=Special:Translate&group=out-blockly-0-all)
+    (choose a language in the upper-right), and start translating!
+
+New translations may take a few months to show up on the live site.
+
+![A photo showing three Vietnamese girls in front of a
+computer.](/images/vietnam.jpg)
+
+## Klingon translations
+
+On 1 April 2014 we released a
+[Klingon translation of Blockly](https://blockly-demo.appspot.com/static/demos/code/index.html?lang=tlh#ortpyd).
+Klingon is an unusual choice for a translation, and on this page we wanted to
+give some context on the hows and whys, as well as how you can help.
+
+![A stack of blocks in Klingon.](/images/klingon.png)
+
+### Why?
+
+Blockly has been translated into over 40 languages, including RTL languages such
+as Arabic and Hebrew. We feel that it is important that novice programmers are
+able to learn the fundamentals of programming in their own language, before
+making the transition to conventional English-based programming languages.
+
+Klingon is a real language in every sense of the word. It is not just a
+collection of made-up words thrown together for a movie. Instead, it has been
+crafted by linguists over the course of decades. The Klingon language has a
+complicated grammar that is completely unique.
+
+Consider word order. English follows the Subject-Verb-Object order ("The cat
+eats the food."). Hungarian follows the Object-Subject-Verb order ("The food
+the cat eats."). Hebrew follows the Verb-Subject-Object order ("Eats the cat
+the food."). Klingon is the most bizarre, with Object-Verb-Subject order ("The
+food eats the cat."). Supporting Klingon is the ultimate test of Blockly's
+flexibility. Block inputs need to be reordered, suffix groups need to be added,
+rules for plurals need to be rethought. Infrastructure improvements made during
+the course of translating to Klingon help us support all languages.
+
+### How?
+
+Most of [Blockly's translations](/guides/contribute/core/translating) are done by volunteers
+using Translatewiki. Unfortunately, Klingon is not in their language matrix.
+As a result, Klingon contributors need to edit the translation manually:
+
+[msg/json/tlh.json](https://github.com/RaspberryPiFoundation/blockly/blob/main/packages/blockly/msg/json/tlh.json)
+
+See the `en` files in each directory for the English phrases (including
+those not yet translated to Klingon).
+We actively do not want tooltip messages or help URLs translated since they
+offer useful context for those new to Klingon.
+
+All phrases _must_ be manually translated. Bing Translate produces such
+translations as `"Library" -> "be'nI''a'wI', Datu'"` which actually means
+`"discover my big sister"`.
+Clearly this would be an inadvisable phrase to use in a Klingon environment.