Write the manual for the person using the desktop

docs/ is engineering artifacts -- design specs, plans, an upstream ledger -- and none of it is written for the person who has to live here. Five chapters that are: coming from another desktop, the keyboard, windows and workspaces, when something breaks, and making it yours. Rendered inside Settings rather than opened in a browser, so a chapter that says "the Displays page reverts after fifteen seconds" is one click from the Displays page. Qt's markdown renderer does the work; one chapter per Text, because Text has an implicit texture size limit and a document long enough to hit it goes blank rather than complaining. The chapters live beside the shell in manual/ rather than at the repository root, which departs from the plan. The reason is the path: the shell finds them through Quickshell.shellDir, which is correct wherever the repository is, whereas walking upward out of the shell directory is only correct by accident. The contract fails that pattern if it comes back. The contract also pins the set both ways -- every chapter listed exists, every chapter that exists is listed -- because a renamed file shows an error card where a chapter should be, which reads as a broken manual rather than as a moved file.
2026-08-22 01:11:46 -04:00
parent 9202697734
commit 202b5b89ac
14 changed files with 459 additions and 2 deletions
@@ -0,0 +1,53 @@
+# Coming from another desktop
+
+Panama is Hyprland with a shell built to replace a GNOME session, so most of
+what you know still applies. The differences worth knowing on day one are
+below. Nothing here is a preference you have to accept: every one of them is
+adjustable in Settings.
+
+## Windows arrange themselves
+
+The biggest change. You do not drag windows into position. Open a second
+window and the screen splits; open a third and it splits again. This is
+called tiling, and after a day of it, dragging windows feels like making
+your own bed in a hotel.
+
+Two things follow from it:
+
+- **There is no minimise.** A minimised window is a window you have hidden
+  from a layout that was managing it for you. Use `Super + Shift + X` to
+  push a window to the scratchpad and `Super + X` to bring it back, which is
+  the same idea without the layout losing track of it.
+- **Floating still exists.** `Super + Ctrl + C` makes a window float above
+  the layout, for the dialog that was never meant to be tiled.
+
+## Workspaces replace the taskbar
+
+Instead of many windows on one screen, use many screens. `Alt + 1` through
+`Alt + 0` jump straight to a workspace; `Alt + Shift + 1` sends the window
+you are looking at to workspace one. `Super + backtick` shows all of them at
+once.
+
+If you came from macOS, this is Spaces with the friction removed. If you came
+from Windows, it is virtual desktops that are actually worth using because
+switching is one key rather than three.
+
+## The launcher is the menu
+
+There is no applications menu to browse. `Super + Space` opens a search box
+that finds applications, files, clipboard history, emoji, and does
+arithmetic. Type three letters of what you want.
+
+This replaces the Start menu, Spotlight, the GNOME overview's app grid, and
+the run dialog, and it is faster than all of them because it never asks you
+to aim at anything.
+
+## What stayed the same
+
+`Super + Tab` still switches windows. The bar is still along the top with a
+clock in the middle and status on the right. There is still a dock. Volume
+and brightness keys still work, and still work on the lock screen. Copy and
+paste are unchanged. Your files are where you left them.
+
+GNOME Settings is still installed for the few panels Panama deliberately does
+not own, and Panama's own Settings hands off to it where that applies.