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
 
@@ -150,14 +154,38 @@ AeroSpace is controlled by commands. For more info see [the list of all availabl
 
 ## 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 introduces it's own concept - workspaces. Basically, workspaces are an emulation
+of Spaces. If the workspace isn't active then all of the windows of that workspace are placed outside of the visible area of the
+screen. Once you switch back to a 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 user quits AeroSpace or before crashing, AeroSpace puts windows back to the center 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.
+
+> [!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 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 +202,5 @@ Overview of 'Displays have separate Spaces'
 
 
 ## Multiple displays
-TODO DOCUMENTATION
 TODO DOCUMENTATION. Add difference with i3