Simplify, update, detail keyboard customization

.wordlist.txt

@@ -61,6 +61,8 @@ multimeter
 keypress
 MCU
 !dilemma
+dilemma
+Dilemma
 TRRS
 KiCad
 Millmax
@@ -99,3 +101,4 @@ Alli # keeps getting detected as a word in youtube video id in embed
 upstreaming
 userspace
 realpath
+usevia # keeps being detected in the url

fw/compile-firmware.md

@@ -12,98 +12,76 @@
 
 # Introduction
 
-The [BastardKB QMK repository](https://github.com/bastardkb/bastardkb-qmk) contains the firmware code and releases for the Bastard Keyboards Charybdis boards.
+The [BastardKB QMK repository](https://github.com/bastardkb/bastardkb-qmk) contains the behavioural firmware code and releases for the Bastard Keyboards Charybdis boards.
 
-While that repository is used as primary source of truth for Bastard Keyboards firmwares as it contains the latest changes and improvements, the maintainers aim at upstreaming all those changes to the official [QMK repository](https://github.com/qmk/qmk_firmware).
+The keymaps are stored in the [BastardKB QMK userspace repository][bkbus].
 
-While the behavioral code is stored on the QMK repository, the keymaps are stored in our [QMK userspace](https://github.com/Bastardkb/qmk_userspace).
+The QMK repository repository is used as primary source of truth for Bastard Keyboards firmwares and contains the latest changes and improvements.
+The maintainers aim at upstreaming all those changes to the official [QMK repository](https://github.com/qmk/qmk_firmware).
 
-This page details how to compile your own firmware. Building from source is useful to people who want to customize their keyboard and keymaps beyond what Via offers. This involves using a command-line interface, writing C code, and compiling this code into the final firmware file.
+This page details how to build your own firmware. 
+Building from source is useful to people who want to customize their keyboard and keymaps beyond what Via offers. 
+You will have to modify the keymap `C` code, and from there compile your firmware either using Github actions or the local command line.
 
 If that seems too complicated, you can also use one of the default releases, or VIA.
 
 # Pre-requisites
 
-## Working QMK environment
-
-Make sure you have a functional QMK environment. See [QMK Docs](https://docs.qmk.fm/#/newbs) for details. At this point, **you don't need** to run `qmk setup`.
-
-## BastardKb QMK fork
-
-Clone the BKB QMK repository, using either github desktop or the command line, and switch to the `bkb-master` branch:
-
-```shell
-git clone https://github.com/bastardkb/bastardkb-qmk
-cd bastardkb-qmk
-git checkout -b bkb-master origin/bkb-master
-```
-
-Now that you've cloned the repository, `cd` into it and set it as the default local QMK repository. You also need to do this if you had a previous, separate QMK installation.
-
-```shell
-qmk config user.qmk_home="$(realpath .)" 
-```
-
-{: .info }
-If you have multiple QMK installations, you will need to manually set the qmk home path again to use the other ones.
-
-That's all you needed to do with the QMK repository.
-From here on, **we will only focus on the Userspace repository.**
-
 ## BastardKb userspace
 
 While the QMK repository contains the logic behind the keyboards, the keymaps are in the userspace repository.
 
-**If you are going to create your own keymaps, you should fork the repository.**
+**If you are going to create your own keymaps, the first step is to fork the [BastardKB QMK userspace repository][bkbus].**
 
-In a separate folder, clone the BKB QMK repository, using either github desktop or the command line:
 
+This way, you can:
 
-```shell
-git clone https://github.com/bastardkb/qmk_userspace # or, your own fork
-```
+- track changes
+- use Github actions to compile your keymap
+- (if relevant) contribute your keymap to the origin Bastard KB QMK Userspace
+
+In a separate folder, clone the fork you just created, using either Github desktop or the command line:
 
-Next, `cd` into the repository and enable userspace:
 
 ```shell
-cd qmk_userspace
-qmk config user.overlay_dir="$(realpath .)"
+git clone https://github.com/my_username/qmk_userspace 
 ```
 
-## Github actions {#actions-requirements}
-
-If you want to use Github actions to compile your firmware (rather than the console), you will need to:
-
-- fork the BastardKB QMK Userspace repository
-- in the `Actions` tab, enable workflows
-
-
 # Creating your keymap
 
-If you want to create your own keymap, **we heavily recommend to create your own fork of the BastardKB QMK userspace.**
-
-This way, you can:
-
-- track changes
-- use Github actions to compile your keymap
-- (if relevant) contribute your keymap to the origin Bastard KB QMK Userspace
+If you want to create your own keymap, **make sure you have forked the [BastardKB QMK userspace repository][bkbus].**
 
 Create a separate folder in the relevant folder, eg:
 
 ```
 keyboards/bastardkb/charybdis/4x6/keymaps/my-keymap/
 ```
 
+
+{: .note }
+By convention, your keymap name must be all lowercase, without spaces.
+
 Then, the easiest is to copy over an existing keymap (eg. `vendor`) over, and modify from there.
 
+# Compiling your firmware using Github actions
 
-# Compiling with Github Actions
+By using github actions, you can have Github compile your firmware without having to bother with a local QMK installation and console commands.
 
-First, make sure you have went through the [Github actions requirements section above](#actions-requirements).
+## Pre-requisites {#actions-requirements}
+
+If you want to use Github actions to compile your firmware (rather than doing it locally in the console), you will need to:
+
+- fork the BastardKB QMK Userspace repository
+- **in the `Actions` tab, enable workflows**
+
+
+## Compiling your firmware
+
+First, make sure you have gone through the [Github actions requirements section above](#actions-requirements).
 
 After cloning the BastardKB userspace repository, it is already configured to work with the BastardKB QMK fork - so no need for additional configuration on that side.
 
-If you created your own keymap, you will need to add it to the list of keympaps to be compiled in `qmk.json`, for example:
+Once you created your own keymap, you will need to add it to the list of keymaps to be compiled in `qmk.json`, for example:
 
 ```shell
 {
@@ -124,15 +102,55 @@
 1. Inspect the Releases tab on your repository for the latest firmware build
 
 
-# Compiling with console
+# Compiling your firmware using the local command line
+
+You can also compile your firmware through your local command line. This requires you to be familiar with the console, and doing some additional configuration.
+
+## Pre-requisites
+
+### Working QMK environment
+
+Make sure you have a functional QMK environment. See [QMK Docs](https://docs.qmk.fm/#/newbs) for details. At this point, **you don't need** to run `qmk setup`.
+
+### BastardKb QMK fork
+
+Clone the BKB QMK repository, using either github desktop or the command line, and switch to the `bkb-master` branch:
+
+```shell
+git clone https://github.com/bastardkb/bastardkb-qmk
+cd bastardkb-qmk
+git checkout -b bkb-master origin/bkb-master
+```
+
+Now that you've cloned the repository, `cd` into it and set it as the default local QMK repository. You also need to do this if you had a previous, separate QMK installation.
+
+```shell
+qmk config user.qmk_home="$(realpath .)" 
+```
+
+{: .info }
+If you have multiple QMK installations, you will need to manually set the qmk home path again to use the other ones.
+
+That's all you needed to do with the QMK repository.
+From here on, **we will only focus on the userspace repository.**
+
+### QMK Userspace
+
+Next, `cd` into your userspace fork and enable userspace:
+
+```shell
+qmk config user.overlay_dir="$(realpath .)"
+```
+
+## Compiling your firmware
 
 Once in the QMK userspace repository, compiling a keymap works the same as normal:
 
 ```shell
 qmk compile -c -kb bastardkb/{keyboard} -km {keymap}
 ```
 
-## `{keyboard}` argument
+### `{keyboard}` argument
 
 `{keyboard}` corresponds to the physical keyboard you are building the firmware for. It can be one of the following:
 
@@ -142,10 +160,10 @@
 - `scylla`: the 4x6+5 [Scylla](https://github.com/Bastardkb/Scylla)
 - `skeletyl`: the 3x5+3 [Skeletyl](https://github.com/Bastardkb/Skeletyl/)
 - `tbkmini`: the 3x6+3 [TBK Mini](https://github.com/Bastardkb/TBK-Mini/)
 - `dilemma/3x5_3`: the 3x5+3 [Dilemma](https://github.com/bastardkb/dilemma/)
 - `dilemma/4x6_4`: the 4x6+4 [Dilemma Max](https://github.com/bastardkb/dilemma/)
 
-## `{keymap}` argument
+### `{keymap}` argument
 
 All keyboards have a `vendor` keymap, which is the one officially supported and shipped with Bastard Keyboards.
 
@@ -170,4 +188,5 @@
 
 ---
 
-[flashing]: {{site.baseurl}}/fw/flashing.html
+[flashing]: {{site.baseurl}}/fw/flashing.html
+[bkbus]: https://github.com/Bastardkb/qmk_userspace