Add some examples to the README

Closes #572

README.md

@@ -1,15 +1,15 @@
 [![github banner-short](https://user-images.githubusercontent.com/22394/26989908-dd99cc2c-4d22-11e7-9576-c6aeada2bd63.png)](http://luckyframework.org)
 
-* Catches bugs you didn't know you had
-* Runs incredibly quickly with low memory usage
-* Helps you spend more time on code instead of debugging and writing tests.
+- Catches bugs you didn't know you had
+- Runs incredibly quickly with low memory usage
+- Helps you spend more time on code instead of debugging and writing tests.
 
 Learn more about [what makes Lucky special](https://luckyframework.org/why-lucky/).
 
 ## Coming from Rails?
 
-* [Ruby on Rails to Lucky on Crystal: Blazing fast, fewer bugs, and even more fun.
-](https://hackernoon.com/ruby-on-rails-to-lucky-on-crystal-blazing-fast-fewer-bugs-and-even-more-fun-104010913fec)
+- [Ruby on Rails to Lucky on Crystal: Blazing fast, fewer bugs, and even more fun.
+  ](https://hackernoon.com/ruby-on-rails-to-lucky-on-crystal-blazing-fast-fewer-bugs-and-even-more-fun-104010913fec)
 
 ## Try Lucky
 
@@ -19,6 +19,72 @@ make it easy to get started.
 Feel free to say hi or ask questions on our
 [chat room](https://gitter.im/luckyframework/Lobby).
 
+## What's it look like?
+
+JSON endpoint:
+
+```crystal
+class Api::Users::Show < ApiAction
+  route do
+    json user_json
+  end
+
+  private def user_json
+    user = UserQuery.find(id)
+    {name: user.name, email: user.email}
+  end
+end
+```
+
+Query the database:
+
+```crystal
+# Set up the model
+class User < BaseModel
+  table :users do
+    column last_active_at : Time
+    column last_name : String
+  end
+end
+
+# Add some methods to help query the database
+class UserQuery < User::BaseQuery
+  def recently_active
+    last_active_at.gt(1.week.ago)
+  end
+
+  def sorted_by_last_name
+    last_name.lower.desc_order
+  end
+end
+
+# Query the database
+UserQuery.new.recently_active.sorted_by_last_name
+```
+
+Rendering HTML:
+
+```crystal
+class Users::Index < BrowserAction
+  route do
+    users = UserQuery.new.sorted_by_last_name
+    render IndexPage, users: users
+  end
+end
+
+class Users::IndexPage < MainLayout
+  needs users : UserQuery
+
+  def content
+    ul class: "user-list" do
+      @users.each do |user|
+        li { link user.name, to: Users::Show.with(user.id) }
+      end
+    end
+  end
+end
+```
+
 ## Lucky is growing quickly
 
 Keep up to date by following [@luckyframework](https://twitter.com/luckyframework) on Twitter.
@@ -44,11 +110,11 @@ You need to make sure to install the Crystal dependencies.
 
 ## Thanks & attributions
 
-* SessionHandler, CookieHandler and FlashHandler are based on [Amber](https://github.com/amberframework/amber). Thank you to the Amber team!
-* Thanks to Rails for inspiring many of the ideas that are easy to take for
+- SessionHandler, CookieHandler and FlashHandler are based on [Amber](https://github.com/amberframework/amber). Thank you to the Amber team!
+- Thanks to Rails for inspiring many of the ideas that are easy to take for
   granted. Convention over configuration, removing boilerplate, and most
   importantly - focusing on developer happiness.
-* Thanks to Phoenix, Ecto and Elixir for inspiring LuckyRecord's forms,
+- Thanks to Phoenix, Ecto and Elixir for inspiring LuckyRecord's forms,
   Lucky's single base actions and pipes, and focusing on helpful error
   messages.
-* `lucky watch` based heavily on [Sentry](https://github.com/samueleaton/sentry). Thanks [@samueleaton](https://github.com/samueleaton)!
+- `lucky watch` based heavily on [Sentry](https://github.com/samueleaton/sentry). Thanks [@samueleaton](https://github.com/samueleaton)!