misc improvements

faq.rst

@@ -0,0 +1,8 @@
+==========================
+Frequently Asked Questions
+==========================
+
+Won't Kweb be slow relative to client-side web frameworks?
+----------------------------------------------------------
+
+No.

gettingstarted.rst

@@ -0,0 +1,8 @@
+===============
+Getting Started
+===============
+
+Tools
+-----
+
+* `IntelliJ IDEA <https://www.jetbrains.com/idea/>`_ - The IDE created by the creators of Kot

index.rst

@@ -9,6 +9,6 @@ Kweb: The Contrarian Web Framework
 Create fast, beautiful, efficient, powerful websites in Kotlin.
 
 .. toctree::
-
    intro
-
+   gettingstarted
+   faq

intro.rst

@@ -2,16 +2,16 @@
 Introduction
 ============
 
-A new paradigm for webapps
---------------------------
+A new paradigm for website architecture
+---------------------------------------
 
-Most websites are two pieces of tightly coupled software:
+Most websites are two pieces of tightly coupled software, *client* and *server*.
 
  * Client
     * Runs in the browser
     * Responsible for user interaction
     * Typically written in JavaScript
-    * Runs in an "untrusted" environment
+    * Runs in an untrusted  environment
 
  * Server
     * Runs in a datacenter
@@ -23,20 +23,24 @@ The first runs on the web server, the second runs in the web browser.  Coders wo
 appear like a single piece of software to the website visitor, but this requires a lot of hidden complexity.
 
 Kweb allows you to write your entire app as a single piece of software, as
-if it was running on a single computer.  It's written in `Kotlin <https://kotlinlang.org/>`_, a
-powerful new programming language that is rapidly growing in popularity.
+if it was running on a single computer.  Kweb does this by moving as much of the business logic to the server
+as possible, leaving a simple but powerful interface to the web browser.
 
-Kweb does this by moving as much of the business logic to the server as possible, and then allowing
-a programmer to interact directly with the browser DOM and JavaScript engine as if was running
-locally to the server.
+It's written in `Kotlin <https://kotlinlang.org/>`_, a
+powerful programming language that is rapidly growing in popularity.
 
-Through a clever set of optimizations, Kweb avoids unnecessary delays waiting for server roundtrips,
-and minimizes network latency through use of WebSockets.
+How does it work?
+-----------------
 
-Build Powerful, fast, beautiful websites, painlessly and quickly
-----------------------------------------------------------------
+Kweb is a self-contained Kotlin library that can be added easily to new or existing projects.  When Kweb receives
+a HTTP request it responds with a small HTML file including instructions for building the page, and a
+client which connects back to the web server via a WebSocket.  The client then waits and listens for instructions
+from the server.
 
-* A single unified codebase for your webapp, no artificial separation between browser and server
+Features
+--------
+* A single unified codebase for your webapp
 * Code in Kotlin (`Why? <https://steve-yegge.blogspot.com/2017/05/why-kotlin-is-better-than-whatever-dumb.html?m=1>`_)
+* Bind DOM values directly to a value in your database and have them update in realtime
 * Makes efficient use of WebSockets and "preloading" of instructions to the browser
-* A smooth upgrade path to Web Assembly
+* A smooth upgrade path to WebAssembly once its ready