Merge pull request #29 from printeers/feature/readme-clarifications

README.md: Improve some instructions

README.md

@@ -9,14 +9,16 @@ A basic trek workflow looks like this:
 - Commit the migration file to an VCS like git. The changed pgModeler schema and the migration SQL file may be code-reviewed.
 - Deploy the latest version of `my_database` to a live database by running `trek apply`. Trek uses [golang-migrate](https://github.com/golang-migrate/migrate) to keep track of the latest version deployed to a database, and to deploy new migration files to the database. (You may skip `trek apply` and integrate with `golang-migrate` manually.)
 
-A developer could run `trek generate --stdout` to continuously watch the pgModeler model for updates (on save) and write PostgreSQL DDL to stdout.
+A developer could run `trek generate --dev --stdout` to continuously watch the pgModeler model for updates (on save) and write PostgreSQL DDL to stdout.
 
 Trek is an opinionated tool. We built it to do one thing and do it well: convert pgModeler schema design into versioned migrations. Trek is exclusively designed for use with PostgreSQL, and we firmly intend to maintain this focus. As such, we will not be considering or adding support for any other database systems.
 
 ## Compatibility
 
 Trek works with PostgreSQL version 13 or newer. We build trek with the latest stable version of pgModeler.
 
+We develop and test Trek on Linux. Trek may work on other platforms via Docker.
+
 ## Installation
 
 ```bash
@@ -37,23 +39,24 @@ trek --force-embedded-migra=true generate --stdout
 
 _Note that the embedded migra is [built using a patched schemainspect library](internal/embedded/migra/build-migra.Dockerfile), which is [awaiting upstream merge](https://github.com/djrobstep/schemainspect/pull/67)._
 
-If you have trouble setting up pgmodeler-cli
-
-## MacOS
+## MacOS / Windows
 
-If you're running on a mac (for which the embedded `migra` doesn't work), you may want to consider using `docker` to run trek under `linux/amd64` (Rosetta emulation).
+If you're running on MacOS or Windows, then the embedded `migra` doesn't work. Either install migra manually or use `docker` to run trek under `linux/amd64` (Rosetta emulation).
 
 ## Docker
 
 To run `trek` in docker:
 
 ```bash
+cd your_trek_working_directory
 docker run -v ./:/data ghcr.io/printeers/trek:latest-pgmodeler trek ...
 ```
 
-## Setup
+## Setup a trek working directory manually
+
+We recommended to use `trek init`, but you may setup a working directory manually.
 
-Create `trek.yaml`:
+Inside a directory create `trek.yaml`:
 
 ```yaml
 model_name: <model_name>
@@ -65,11 +68,11 @@ db_users:
 
 Create `<model_name>.dbm` using pgModeler.
 
-## Creating migrations
+## Generating a new migration
 
 `trek generate some-migration`
 
-Use the `--dev` flag to continuously watch for file changes.
+Use the `--dev` flag to continuously watch for file changes. Use the `--stdout` flag to write migrations to stdout. You must omit the migration name when using `--stdout`.
 
 ## Applying the migrations