diff --git a/README.md b/README.md
index 21604ddb..6ebf614f 100644
--- a/README.md
+++ b/README.md
@@ -3,44 +3,46 @@
 ![Build](https://github.com/mikefarah/yq/workflows/Build/badge.svg)  ![Docker Pulls](https://img.shields.io/docker/pulls/mikefarah/yq.svg) ![Github Releases (by Release)](https://img.shields.io/github/downloads/mikefarah/yq/total.svg) ![Go Report](https://goreportcard.com/badge/github.com/mikefarah/yq) ![CodeQL](https://github.com/mikefarah/yq/workflows/CodeQL/badge.svg)
 
 
-a lightweight and portable command-line YAML, JSON, INI and XML processor. `yq` uses [jq](https://github.com/stedolan/jq) like syntax but works with yaml files as well as json, xml, ini, properties, csv and tsv. It doesn't yet support everything `jq` does - but it does support the most common operations and functions, and more is being added continuously.
+A lightweight and portable command-line YAML, JSON, INI and XML processor. `yq` uses [jq](https://github.com/stedolan/jq) (a popular JSON processor) like syntax but works with yaml files as well as json, xml, ini, properties, csv and tsv. It doesn't yet support everything `jq` does - but it does support the most common operations and functions, and more is being added continuously.
 
-yq is written in go - so you can download a dependency free binary for your platform and you are good to go! If you prefer there are a variety of package managers that can be used as well as Docker and Podman, all listed below.
+yq is written in Go - so you can download a dependency free binary for your platform and you are good to go! If you prefer there are a variety of package managers that can be used as well as Docker and Podman, all listed below.
 
 ## Quick Usage Guide
 
-Read a value:
+### Basic Operations
+
+**Read a value:**
 ```bash
 yq '.a.b[0].c' file.yaml
 ```
 
-Pipe from STDIN:
+**Pipe from STDIN:**
 ```bash
 yq '.a.b[0].c' < file.yaml
 ```
 
-Update a yaml file, in place
+**Update a yaml file in place:**
 ```bash
 yq -i '.a.b[0].c = "cool"' file.yaml
 ```
 
-Update using environment variables
+**Update using environment variables:**
 ```bash
 NAME=mike yq -i '.a.b[0].c = strenv(NAME)' file.yaml
 ```
 
-Merge multiple files
+### Advanced Operations
+
+**Merge multiple files:**
 ```bash
 # merge two files
 yq -n 'load("file1.yaml") * load("file2.yaml")'
 
-# merge using globs:
-# note the use of `ea` to evaluate all the files at once
-# instead of in sequence
+# merge using globs (note: `ea` evaluates all files at once instead of in sequence)
 yq ea '. as $item ireduce ({}; . * $item )' path/to/*.yml
 ```
 
-Multiple updates to a yaml file
+**Multiple updates to a yaml file:**
 ```bash
 yq -i '
   .a.b[0].c = "cool" |
@@ -49,14 +51,22 @@ yq -i '
 ' file.yaml
 ```
 
-Find and update an item in an array:
+**Find and update an item in an array:**
 ```bash
-yq '(.[] | select(.name == "foo") | .address) = "12 cat st"'
+# Note: requires input file - add your file at the end
+yq -i '(.[] | select(.name == "foo") | .address) = "12 cat st"' data.yaml
 ```
 
-Convert JSON to YAML
+**Convert between formats:**
 ```bash
+# Convert JSON to YAML (pretty print)
 yq -Poy sample.json
+
+# Convert YAML to JSON
+yq -o json file.yaml
+
+# Convert XML to YAML
+yq -o yaml file.xml
 ```
 
 See [recipes](https://mikefarah.gitbook.io/yq/recipes) for more examples and the [documentation](https://mikefarah.gitbook.io/yq/) for more information.
@@ -68,31 +78,31 @@ Take a look at the discussions for [common questions](https://github.com/mikefar
 ### [Download the latest binary](https://github.com/mikefarah/yq/releases/latest)
 
 ### wget
-Use wget to download, gzipped pre-compiled binaries:
+Use wget to download pre-compiled binaries. Choose your platform and architecture:
 
-
-For instance, VERSION=v4.2.0 and BINARY=yq_linux_amd64
-
-#### Compressed via tar.gz
+**For Linux (example):**
 ```bash
-wget https://github.com/mikefarah/yq/releases/download/${VERSION}/${BINARY}.tar.gz -O - |\
-  tar xz && mv ${BINARY} /usr/local/bin/yq
-```
+# Set your platform variables (adjust as needed)
+VERSION=v4.2.0
+PLATFORM=linux_amd64
 
-#### Plain binary
+# Download compressed binary
+wget https://github.com/mikefarah/yq/releases/download/${VERSION}/yq_${PLATFORM}.tar.gz -O - |\
+  tar xz && sudo mv yq_${PLATFORM} /usr/local/bin/yq
 
-```bash
-wget https://github.com/mikefarah/yq/releases/download/${VERSION}/${BINARY} -O /usr/local/bin/yq &&\
+# Or download plain binary
+wget https://github.com/mikefarah/yq/releases/download/${VERSION}/yq_${PLATFORM} -O /usr/local/bin/yq &&\
     chmod +x /usr/local/bin/yq
 ```
 
-#### Latest version
-
+**Latest version (Linux AMD64):**
 ```bash
 wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq &&\
     chmod +x /usr/local/bin/yq
 ```
 
+**Available platforms:** `linux_amd64`, `linux_arm64`, `linux_arm`, `linux_386`, `darwin_amd64`, `darwin_arm64`, `windows_amd64`, `windows_386`, etc.
+
 ### MacOS / Linux via Homebrew:
 Using [Homebrew](https://brew.sh/)
 ```
@@ -123,28 +133,31 @@ rm /etc/myfile.tmp
 ```
 
 ### Run with Docker or Podman
-#### Oneshot use:
 
+#### One-time use:
 ```bash
-docker run --rm -v "${PWD}":/workdir mikefarah/yq [command] [flags] [expression ]FILE...
+# Docker - process files in current directory
+docker run --rm -v "${PWD}":/workdir mikefarah/yq '.a.b[0].c' file.yaml
+
+# Podman - same usage as Docker
+podman run --rm -v "${PWD}":/workdir mikefarah/yq '.a.b[0].c' file.yaml
 ```
 
-Note that you can run `yq` in docker without network access and other privileges if you desire,
-namely `--security-opt=no-new-privileges --cap-drop all --network none`.
-
+**Security note:** You can run `yq` in Docker with restricted privileges:
 ```bash
-podman run --rm -v "${PWD}":/workdir mikefarah/yq [command] [flags] [expression ]FILE...
+docker run --rm --security-opt=no-new-privileges --cap-drop all --network none \
+  -v "${PWD}":/workdir mikefarah/yq '.a.b[0].c' file.yaml
 ```
 
-#### Pipe in via STDIN:
+#### Pipe data via STDIN:
 
-You'll need to pass the `-i\--interactive` flag to docker:
+You'll need to pass the `-i --interactive` flag to Docker/Podman:
 
 ```bash
+# Process piped data
 docker run -i --rm mikefarah/yq '.this.thing' < myfile.yml
-```
 
-```bash
+# Same with Podman
 podman run -i --rm mikefarah/yq '.this.thing' < myfile.yml
 ```
 
@@ -340,7 +353,7 @@ gah install yq
 - Supports yaml [front matter](https://mikefarah.gitbook.io/yq/usage/front-matter) blocks (e.g. jekyll/assemble)
 - Colorized yaml output
 - [Date/Time manipulation and formatting with TZ](https://mikefarah.gitbook.io/yq/operators/datetime)
-- [Deeply data structures](https://mikefarah.gitbook.io/yq/operators/traverse-read)
+- [Deep data structures](https://mikefarah.gitbook.io/yq/operators/traverse-read)
 - [Sort keys](https://mikefarah.gitbook.io/yq/operators/sort-keys)
 - Manipulate yaml [comments](https://mikefarah.gitbook.io/yq/operators/comment-operators), [styling](https://mikefarah.gitbook.io/yq/operators/style), [tags](https://mikefarah.gitbook.io/yq/operators/tag) and [anchors and aliases](https://mikefarah.gitbook.io/yq/operators/anchor-and-alias-operators).
 - [Update in place](https://mikefarah.gitbook.io/yq/v/v4.x/commands/evaluate#flags)
@@ -423,6 +436,27 @@ Flags:
 
 Use "yq [command] --help" for more information about a command.
 ```
+
+## Troubleshooting
+
+### Common Issues
+
+**PowerShell quoting issues:**
+```powershell
+# Use single quotes for expressions
+yq '.a.b[0].c' file.yaml
+
+# Or escape double quotes
+yq ".a.b[0].c = \"value\"" file.yaml
+```
+
+### Getting Help
+
+- **Check existing issues**: [GitHub Issues](https://github.com/mikefarah/yq/issues)
+- **Ask questions**: [GitHub Discussions](https://github.com/mikefarah/yq/discussions)
+- **Documentation**: [Complete documentation](https://mikefarah.gitbook.io/yq/)
+- **Examples**: [Recipes and examples](https://mikefarah.gitbook.io/yq/recipes)
+
 ## Known Issues / Missing Features
 - `yq` attempts to preserve comment positions and whitespace as much as possible, but it does not handle all scenarios (see https://github.com/go-yaml/yaml/tree/v3 for details)
 - Powershell has its own...[opinions on quoting yq](https://mikefarah.gitbook.io/yq/usage/tips-and-tricks#quotes-in-windows-powershell)