A quick guide

docs/CHANGELOG.md

@@ -31,3 +31,10 @@
 - Upgrade to Textual version 0.76.0
 - Change logic to render bindings in help modal to reflect new Textual API.
 - Sort order of requests in the tree improved.
+
+
+---
+
+!!! note
+    Changes prior to 1.11.0 are not documented here.
+    Please see the [Releases page](https://github.com/darrenburns/posting/releases) on GitHub for information on changes prior to 1.11.0.

docs/guide/index.md

@@ -8,4 +8,68 @@ pipx install posting
 
 Python 3.11 or later is required.
 
-More installation methods (`brew`, etc) will be added soon.
+More installation methods (`brew`, etc) will be added soon.
+
+## A quick introduction
+
+This introduction will show you how to create a simple POST request to the [JSONPlaceholder](https://jsonplaceholder.typicode.com/) mock API to create a new user. It focuses on an efficient keyboard-driven workflow, but you can also use the mouse if you prefer.
+
+### Collections and requests
+
+A *collection* is simply a directory which may contain requests saved by Posting.
+
+If you launch Posting without specifying a collection, any requests you create will be saved in the "default" collection.
+This is a directory reserved by Posting on your filesystem, and unrelated to the directory you launched Posting from.
+
+This is fine for quick throwaway requests, but you'll probably want to create a new collection for each project you work on so that you can check it into version control.
+
+To create a new collection, simply create a new directory and pass it into Posting:
+
+```bash
+mkdir my-collection
+posting --collection my-collection
+```
+
+Now, any requests you create will be saved in the `my-collection` directory as simple YAML files with the `.posting.yaml` extension.
+
+### Creating a request
+
+When you launch Posting, no request is open.
+
+You can immediately start creating a request, and then save it to disk with ++ctrl+s++.
+Let's do just that.
+We'll create a simple POST request to the [JSONPlaceholder](https://jsonplaceholder.typicode.com/) mock API to create a new user.
+
+Press ++ctrl+t++ to open the request method dropdown, then press ++p++ to quickly select the `POST` method.
+
+Press ++tab++ to move focus to the next widget, which is the URL bar. The URL bar can also be focused with ++ctrl+l++. Type `https://jsonplaceholder.typicode.com/users` into the URL bar.
+
+### Adding a JSON body
+
+Press ++ctrl+o++ to enter "jump mode", then press ++w++ to quickly jump to the "Body" tab.
+
+Press ++j++ (or ++down++) to move the cursor down to the dropdown. Press ++enter++ to open it, and select the option `Raw (json, text, etc.)`.
+
+Move down to the text area below using ++j++ (or ++down++), and type (or paste) the JSON below. 
+
+```json
+{
+  "name": "John Doe",
+  "username": "johndoe",
+  "email": "[email protected]"
+}
+```
+
+### Viewing keyboard shortcuts
+
+Now is probably a good time to note that you can see the full list of keyboard shortcuts for the focused widget by pressing ++f1++. The text area widget in particular has a lot of useful shortcuts and supports things like undo/redo.
+
+
+### Sending the request
+
+Press ++ctrl+j++ to send the request. This shortcut works globally.
+
+### Saving the request
+
+Finally, press ++ctrl+s++ to save the request to disk.
+Fill out the form on the modal that appears, and press ++enter++ or ++ctrl+n++ to write the request to disk.

docs/guide/requests.md

@@ -25,15 +25,26 @@ params:
   value: 'true'
 ```
 
-## Creating a request
+## Creating a new request
 
-Press ++ctrl+s++ to save the current request.
-A dialog will appear, prompting you to give the request a name, and to select a directory to save it in.
+Press ++ctrl+n++ to create a new request.
 
-If you already have a collection loaded, the directory will be pre-selected based on the location of the cursor in the sidebar, so moving the cursor to the correct location before pressing ++ctrl+s++ will save you from needing to type the path.
+You'll be prompted to supply a name for the request.
+By default, this name is used to generate the filename, but you can also choose your own filename if you wish.
+
+!!! tip
+    If you already have a collection loaded, the directory will be pre-selected based on the location of the cursor in the collection tree, so moving the cursor to the correct location *before* pressing ++ctrl+n++ will save you from needing to type out the path.
 
 Within the "Directory" field of this dialog, it's important to note that `.` refers to the currently loaded *collection* directory (that is, the directory that was loaded using the `--collection` option), and *not* necessarily the current working directory.
 
+## Saving a request
+
+Press ++ctrl+s++ to save the currently open request.
+
+If you haven't saved the request yet, a dialog will appear, prompting you to give the request a name, and to select a directory to save it in.
+
+If the request is already saved on disk, ++ctrl+s++ will overwrite the previous version with your new changes.
+
 ## Loading requests
 
 Requests are stored on your file system as simple YAML files, suffixed with `.posting.yaml`.