Improve getting started documentation.

guides/deployment/readme.md

@@ -16,7 +16,7 @@ Falcon can be deployed into production either as a standalone application server
 
 `falcon host` loads configuration from the `falcon.rb` file in your application directory. This file contains configuration blocks which define how to host the application and any related services. This file should generally be executable and it invokes `falcon host` which starts all defined services.
 
-Here is a basic example which hosts a rack application:
+Here is a basic example which hosts a rack application using :
 
 ~~~ ruby
 #!/usr/bin/env falcon-host
@@ -67,22 +67,10 @@ You can verify this is working using `nghttp -v http://localhost:3000`.
 
 Falcon can replace Nginx as a virtual server for Ruby applications.
 
-~~~
-/--------------------\
-|   Client Browser   |
-\--------------------/
-          ||          
-  (TLS + HTTP/2 TCP)
-          ||          
-/--------------------\
-| Falcon Proxy (SNI) |
-\--------------------/
-          ||          
-  (HTTP/2 UNIX PIPE)
-          ||          
-/--------------------\
-| Application Server |   (Rack Compatible)
-\--------------------/
+~~~ mermaid
+graph TD;
+	client[Client Browser] -->|TLS + HTTP/2 TCP| proxy["Falcon Proxy (SNI)"];
+	proxy -->|HTTP/2 UNIX PIPE| server["Application Server (Rack Compatible)"];
 ~~~
 
 You need to create a `falcon.rb` configuration in the root of your applications, and start the virtual host:

guides/getting-started/readme.md

@@ -2,27 +2,57 @@
 
 This guide explains how to use Falcon for Ruby web application development.
 
-## Falcon Serve
+## Installation
 
-You can run `falcon serve` directly. It will load the `config.ru` and start serving on `https://localhost:9292`.
+Add the gem to your project:
 
-To run on a different port:
+~~~ bash
+$ bundle add falcon
+~~~
+
+Or, if you prefer, install it globally:
 
 ~~~ bash
-$ falcon serve --port 3000
+$ gem install falcon
 ~~~
 
-### Integration with Guard
+## Core Concepts
 
-Falcon can restart very quickly and is ideal for use with guard. See [guard-falcon] for more details.
+Falcon is a high-performance web server for Ruby. It is designed to be fast, lightweight, and easy to use.
 
-[guard-falcon]: https://github.com/socketry/guard-falcon
+- **Asynchronous**: Falcon is built on top of the fiber scheduler and the [async gem](https://github.com/socketry/async) which allow it to handle thousands of connections concurrently.
+- **Rack Compatible**: Falcon is a Rack server. It can run any Rack application, including Rails, Sinatra, and Roda with no modifications.
+- **Secure**: Falcon supports TLS out of the box. It can generate self-signed certificates for localhost.
+- **HTTP/2**: Falcon is build on top of the [async-http gem](https://github.com/socketry/async-http) which supports HTTP/2. It can serve multiple requests over a single connection.
+- **WebSockets**: Falcon supports WebSockets using the [async-websocket gem](https://github.com/socketry/async-websocket) which takes advantage of Rack 3 streaming responses. You can build complex real-time applications with ease.
 
-### Integration with Capybara
+### Rack
 
-Falcon can run in the same process on a different thread, so it's great for use with Capybara (and shared ActiveRecord transactions). See [falcon-capybara] for more details.
+Falcon is a Rack server. This means it can run any Rack application, including Rails, Sinatra, and Roda. It is compatible with the Rack 2 and Rack 3 specifications. Typically these applications have a `config.ru` file that defines the application. Falcon can run these applications directly:
 
-[falcon-capybara]: https://github.com/socketry/falcon-capybara
+~~~ ruby
+# config.ru
+
+run do |env|
+	[200, {'Content-Type' => 'text/plain'}, ['Hello, World!']]
+end
+~~~
+
+Then run the application with:
+
+~~~ bash
+$ falcon serve
+~~~
+
+## Running a Local Server
+
+For local application development, you can use the `falcon serve` command. This will start a local server on `https://localhost:9292`. Falcon generates self-signed certificates for `localhost`. This allows you to test your application with HTTPS locally.
+
+To run on a different port:
+
+~~~ bash
+$ falcon serve --port 3000
+~~~
 
 ### Using with Rackup