Minor documentation improvements

.gitattributes

@@ -1,7 +1,9 @@
 /.gitattributes export-ignore
 /.github/workflows/ export-ignore
 /.gitignore export-ignore
+/docs/ export-ignore
 /examples/ export-ignore
+/mkdocs.yml export-ignore
 /phpunit.xml.dist export-ignore
 /phpunit.xml.legacy export-ignore
 /tests/ export-ignore

README.md

@@ -11,27 +11,10 @@ Framework X – the simple and fast micro framework for building reactive web ap
 
 ## Quickstart
 
-First manually change your `composer.json` to include these lines:
-
-```json
-{
-    "repositories": [
-        {
-            "type": "vcs",
-            "url": "https://github.com/clue-access/framework-x"
-        }
-    ]
-}
-```
-
-Simply install Framework X:
-
-```bash
-$ composer require clue/framework-x:dev-main
-```
-
-Once everything is installed, you can now use this example to get started with
-a new `app.php` file:
+Start by creating an empty project directory.
+Next, we can start by taking a look at a simple example application.
+You can use this example to get started by creating a new `app.php` file in your
+empty project directory:
 
 ```php
 <?php
@@ -49,9 +32,38 @@ $app->get('/', function () {
     );
 });
 
+$app->get('/users/{name}', function (Psr\Http\Message\ServerRequestInterface $request) {
+    return new React\Http\Message\Response(
+        200,
+        [],
+        "Hello " . $request->getAttribute('name') . "!\n"
+    );
+});
+
+$app->run();
 $loop->run();
 ```
 
+Next, we need to install X and its dependencies to actually run this project.
+Start by creating a new `composer.json` in the project directory with the following contents:
+
+```json
+{
+    "repositories": [
+        {
+            "type": "vcs",
+            "url": "https://github.com/clue-access/framework-x"
+        }
+    ]
+}
+```
+
+Finally, simply install Framework X:
+
+```bash
+$ composer require clue/framework-x:dev-main
+```
+
 That's it already! The next step is now to serve this web application.
 One of the nice properties of this project is that is works both behind
 traditional web server setups as well as in a stand-alone environment.
@@ -67,41 +79,18 @@ You can now use your favorite webbrowser or command line tool to check your web
 application responds as expected:
 
 ```bash
-$ curl -v http://localhost:8080/
-HTTP/1.1 200 OK
-…
-
+$ curl http://localhost:8080/
 Hello wörld!
 ```
 
 ## Documentation
 
 Hooked?
-See [full documentation](docs/) for more details.
-
->   We use [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) to
->   render our documentation to a pretty HTML version.
->
->   If you want to contribute to the documentation, it's easiest to just run
->   this in a Docker container like this:
->
->   ```bash
->   $ docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
->   ```
->
->   You can access the documentation via `http://localhost:8000`.
->   If you want to generate a static HTML folder for deployment, you can again
->   use a Docker container like this:
->
->   ```bash
->   $ docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build
->   ```
->
->   The resulting `build/docs/` should then be deployed behind a web server (tbd).
->   If you want to add a new documentation file and/or change the page order, make sure the [`mkdocs.yml`](mkdocs.yml)
->   file contains an up-to-date list of all pages.
->
->   Happy hacking!
+See [website](https://framework-x.clue.engineering/) for full documentation.
+
+Found a typo or want to contribute?
+The website documentation is build from the source documentation files in
+the [docs/](docs/) folder.
 
 ## Tests
 

docs/README.md

@@ -0,0 +1,42 @@
+# Framework X documentation
+
+This folder contains the source documentation files for Framework X.
+
+You can see the [website](https://framework-x.clue.engineering/) for the
+user-accessible version.
+
+## Contribute
+
+Found a typo or want to contribute?
+This folder contains everything you need to help out with the documentation.
+
+We use [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) to
+render our documentation to a pretty HTML version.
+
+If you want to contribute to the documentation, it's easiest to just run
+this in a Docker container in the project root directory like this:
+
+```bash
+$ docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
+```
+
+You can access the documentation via `http://localhost:8000`.
+Props to mkdocs, this uses live reloading, so that every change you do while
+this Docker container is running should immediately be reflected in your web
+browser.
+
+If you want to generate a static HTML folder for deployment, you can again
+use a Docker container in the project root directory like this:
+
+```bash
+$ docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build
+```
+
+The resulting `build/docs/` should then be deployed behind a web server.
+See also the [Framework X website repository](https://github.com/clue/framework-x-website)
+for more details about the website itself.
+
+If you want to add a new documentation file and/or change the page order, make sure the [`mkdocs.yml`](../mkdocs.yml)
+file in the project root directory contains an up-to-date list of all pages.
+
+Happy hacking!

docs/best-practices/deployment.md

@@ -52,23 +52,8 @@ Hello wörld!
 ```
 
 You may be wondering how fast a pure PHP web server implementation could possibly be.
-
-```
-$ ab -n10000 -c10 http://localhost:8080/
-…
-Concurrency Level:      10
-Time taken for tests:   0.991 seconds
-Complete requests:      10000
-Failed requests:        0
-Total transferred:      1090000 bytes
-HTML transferred:       130000 bytes
-Requests per second:    10095.17 [#/sec] (mean)
-Time per request:       0.991 [ms] (mean)
-Time per request:       0.099 [ms] (mean, across all concurrent requests)
-Transfer rate:          1074.58 [Kbytes/sec] received
-```
-
-The answer: Very fast!
+In fact, in benchmarks this setup outperforms any traditional PHP stack by orders of magnitude.
+The answer: [Lightning fast!](https://framework-x.clue.engineering/#lightning-fast)
 
 If you're going to use this in production, we still recommend running this
 behind a reverse proxy such as nginx, HAproxy, etc. for TLS termination

docs/getting-started/quickstart.md

@@ -33,6 +33,14 @@ $app->get('/', function () {
     );
 });
 
+$app->get('/users/{name}', function (Psr\Http\Message\ServerRequestInterface $request) {
+    return new React\Http\Message\Response(
+        200,
+        [],
+        "Hello " . $request->getAttribute('name') . "!\n"
+    );
+});
+
 $app->run();
 $loop->run();
 ```

mkdocs.yml

@@ -1,12 +1,19 @@
-site_name: Documentation
+site_name: Framework X documentation
+site_url: https://framework-x.clue.engineering/docs/
 site_dir: build/docs
 extra:
   homepage: ../
 
+repo_url: https://github.com/clue/framework-x
+repo_name: clue/framework-x
+edit_uri: "" # not publicly accessible while in early access
+
 theme:
   name: material
   features:
     - navigation.sections
+  icon:
+    repo: fontawesome/brands/github
 
 markdown_extensions:
   - pymdownx.highlight