modified: docs/guide.md

Author: nikitabobko

.gitignore

@@ -2,6 +2,7 @@
 /.build
 # IDK, AppCode randomly creates this EMPTY file. I have no idea what this is
 /default.profraw
+/.DS_Store
 
 # XCode User settings
 xcuserdata/

docs/guide.md

@@ -123,10 +123,14 @@ enable-normalization-opposite-orientation-for-nested-containers = false
 ```
 
 ### Floating windows
-TODO DOCUMENTATION
 
-Normally, floating windows are not part of the tiling tree. But it's not the case with `focus` command. From `focus` command
-perspective, floating windows are part of the tree. 
+Normally, floating windows are not considered to be part of the [tiling tree](#tree). But it's not the case with
+[`focus`](./commands.md#focus) command.
+
+From [`focus`](./commands.md#focus) command perspective, floating windows are part of [the tree](#tree). The floating window
+parent is determined as the smallest tiling container that contains the center of the floating window.
+
+This technique eliminates the need for an additional binding for focusing floating windows.
 
 ## Default keybindings
 
@@ -142,22 +146,63 @@ AeroSpace uses TOML format for the config. TOML is easy to read, and it supports
 info](https://toml.io/en/)
 
 ### Binding modes
-TODO DOCUMENTATION. For now you can refer to https://i3wm.org/docs/userguide.html#binding_modes
+
+You can create multiple sets of bindings by creating different binding modes. When you switch to a different binding mode, all
+the bindings from the current mode are deactivated, and only the bindings specified in the new mode become active. The initial
+binding mode that AeroSpace starts out with is "main".
+
+This feature is absolutely identical to the one [in i3](https://i3wm.org/docs/userguide.html#binding_modes)
+
+Working with binding modes consists of two parts: 1. defining a binding to switch to the binding mode and 2. declaring the binding
+mode itself.
+
+```toml
+[mode.main.binding] # Declare 'main' binding mode
+alt-r = "mode resize" # 1. Define a binding to switch to 'resize' mode
+
+[mode.resize.binding] # 2. Declare 'resize' binding mode
+minus = 'resize smart -50'
+equal = 'resize smart +50'
+```
 
 ### Commands
 
 AeroSpace is controlled by commands. For more info see [the list of all available commands](./commands.md).
 
 ## Emulation of virtual workspaces
 
-The supposed workflow is to only have one macOS Space (or as many as monitors you have) and don't interact with macOS spaces in
-any way
+Native macOS Spaces have a lot of problems.
+
+- The animation for Spaces switching is slow
+  - You can't disable animation for Spaces switching (you can only make it slightly faster by turning on `Reduce motion` setting,
+    but it's suboptimal)
+- You have a limit of Spaces (up to 16 Spaces with one monitor)
+- You can't create, delete, reorder Spaces with hotkeys
+- Apple doesn't provide public API to create, delete, reorder and switch Spaces
+
+Since Spaces are so hard to deal with, AeroSpace reimplements Spaces and calls them "Workspaces". The idea is that if the
+workspace isn't active then all of its windows are placed outside of the visible area of the screen. Once you switch back to the
+workspace, (by the means of binding, or by choosing the workspace in the tray icon list) windows are placed back to the visible
+area of the screen.
+
+When you exit the AeroSpace or when the AeroSpace is about to crash, AeroSpace will place all windows back to the visible area of
+the screen.
 
-When user quits AeroSpace or before crashing, AeroSpace puts windows back to the center of the screen
+> [!NOTE]
+> For better or worse, macOS doesn't allow to place windows outside of the visible area entirely. You will still be able to see a
+> few pixels of "hidden" windows in the bottom right corner of your screen. That means, that if AeroSpace crashes badly you will
+> still be able to manually "unhide" the windows by dragging these few pixels to the center of the screen.
+
+The supposed workflow of using AeroSpace workspaces is to only have one macOS Space (or as many as monitors you have, if `Displays
+have separate Spaces` is enabled) and don't interact with macOS Spaces anymore.
 
 ### A note on mission control
-TODO DOCUMENTATION
-Enable 'Group windows by application'
+
+For some reason, mission control doesn't like that AeroSpace puts a lot of windows in the bottom right corner of the screen.
+Mission control shows windows too small even if it has enough space to show them bigger.
+
+To workaround it, you can enable `System Settings -> Desktop & Dock -> Group windows by application` setting. For some weird
+reason, it helps.
 
 ### A note on 'Displays have separate Spaces'
 
@@ -174,6 +219,5 @@ Overview of 'Displays have separate Spaces'
 
 
 ## Multiple displays
-TODO DOCUMENTATION
 TODO DOCUMENTATION. Add difference with i3