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

@@ -150,10 +150,28 @@ 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.
 
-When user quits AeroSpace or before crashing, AeroSpace puts windows back to the center of the screen
+- You can't disable animation for Spaces switching
+- 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 screen area.
+Once you switch back to a workspace (by the binding, or by choosing the workspace in the tray icon list) windows are placed 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 bottom right corner of your screen. That means, that if you have some problems with AeroSpace
+> you will still be able to manually "unhide" the windows by dragging these few pixels 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.
+
+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