diff --git a/README.md b/README.md
index bfba3ab..389f7ff 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Ezdoc
 
-A Ruby gem for working with docx files.
+A Ruby gem for creating docx files with a simple, Phlex-inspired DSL.
 
 ## Installation
 
@@ -20,13 +20,166 @@ Or install it yourself as:
 
 ## Usage
 
+### Basic Example
+
 ```ruby
 require 'ezdoc'
+
+Ezdoc::Document.create("output.docx") do |doc|
+  doc.p "Hello World"
+end
 ```
 
+### Paragraphs
+
+```ruby
+Ezdoc::Document.create("output.docx") do |doc|
+  # Simple paragraph
+  doc.p "This is a paragraph."
+
+  # Paragraph with multiple text runs
+  doc.p do
+    doc.text "First part. "
+    doc.text "Second part."
+  end
+end
+```
+
+### Text Formatting
+
+Formatting uses nested blocks. Nesting combines formatting styles.
+
+```ruby
+Ezdoc::Document.create("output.docx") do |doc|
+  doc.p do
+    doc.text "Normal text "
+    doc.b { doc.text "bold" }
+    doc.text " and "
+    doc.i { doc.text "italic" }
+    doc.text " and "
+    doc.u { doc.text "underlined" }
+  end
+
+  # Nested formatting (bold + italic)
+  doc.p do
+    doc.b do
+      doc.i { doc.text "bold and italic" }
+    end
+  end
+end
+```
+
+### Lists
+
+#### Bullet Lists
+
+```ruby
+Ezdoc::Document.create("output.docx") do |doc|
+  doc.ul do
+    doc.li "First item"
+    doc.li "Second item"
+    doc.li { doc.b { doc.text "Bold item" } }
+  end
+end
+```
+
+#### Numbered Lists
+
+```ruby
+Ezdoc::Document.create("output.docx") do |doc|
+  doc.ol do
+    doc.li "First"
+    doc.li "Second"
+    doc.li "Third"
+  end
+end
+```
+
+### Tables
+
+```ruby
+Ezdoc::Document.create("output.docx") do |doc|
+  doc.table do
+    doc.tr do
+      doc.td "Header 1"
+      doc.td "Header 2"
+    end
+    doc.tr do
+      doc.td "Cell 1"
+      doc.td { doc.b { doc.text "Bold cell" } }
+    end
+  end
+end
+```
+
+### Complete Example
+
+```ruby
+Ezdoc::Document.create("report.docx") do |doc|
+  doc.p "Monthly Report"
+
+  doc.p do
+    doc.text "This report contains "
+    doc.b { doc.text "important" }
+    doc.text " information."
+  end
+
+  doc.p "Key Points:"
+
+  doc.ul do
+    doc.li "Revenue increased by 15%"
+    doc.li "Customer satisfaction improved"
+    doc.li { doc.i { doc.text "See appendix for details" } }
+  end
+
+  doc.p "Summary Table:"
+
+  doc.table do
+    doc.tr do
+      doc.td "Metric"
+      doc.td "Value"
+    end
+    doc.tr do
+      doc.td "Revenue"
+      doc.td "$1.2M"
+    end
+    doc.tr do
+      doc.td "Growth"
+      doc.td { doc.b { doc.text "15%" } }
+    end
+  end
+end
+```
+
+## API Reference
+
+| Method | Description |
+|--------|-------------|
+| `p(text)` | Create a paragraph with text |
+| `p { }` | Create a paragraph with block content |
+| `text(value)` | Add text to the current context |
+| `b { }` | Bold formatting |
+| `i { }` | Italic formatting |
+| `u { }` | Underline formatting |
+| `ul { }` | Bullet list |
+| `ol { }` | Numbered list |
+| `li(text)` | List item with text |
+| `li { }` | List item with block content |
+| `table { }` | Table |
+| `tr { }` | Table row |
+| `td(text)` | Table cell with text |
+| `td { }` | Table cell with block content |
+
 ## Development
 
-After checking out the repo, run `bundle install` to install dependencies. Then, run `rake spec` to run the tests.
+After checking out the repo, run `bundle install` to install dependencies. Then, run `rake test` to run the tests.
+
+```bash
+bundle install
+bundle exec rake test      # Run tests
+bundle exec rake rubocop   # Run linter
+bundle exec rake           # Run both
+```
 
 ## License