diff --git a/README.md b/README.md
index 2ba21b85..53eddba0 100644
--- a/README.md
+++ b/README.md
@@ -14,36 +14,11 @@ Scuttlebutt, as well as a platform for writing and running web applications.
3. Make creating and sharing web applications accessible to anyone with a
browser.
-## Building
-
-Builds on Linux (x86_64 and aarch64), MacOS, OpenBSD, and Haiku. Builds for
-all of those host platforms plus mingw64, iOS, and android.
-
-1. Requires openssl (`libssl-dev`, in debian-speak). All other dependencies
- are kept up to date in the tree.
-2. To build, run `make debug` or `make release`. An executable will be
- generated in a subdirectory of `out/`.
-3. It's possible to build for Android, iOS, and Windows on Linux, if you have
- the right dependencies in the right places. `make windebug winrelease
-iosdebug-ipa iosrelease-ipa release-apk`.
-4. To build in docker, `docker build .`.
-5. `make format` will normalize formatting to the coding standard.
-
-## Running
-
-By default, running the built `tildefriends` executable will start a web server
-at . `tildefriends -h` lists further options.
-
-The first user to create an account and log in will be granted administrative
-privileges. Further administration can be done at
-.
-
## Documentation
-Docs are a work in progress:
-.
+Docs are a work in progress in the `docs` folder and in Tilde Friends: .
## License
All code unless otherwise noted in is provided under the
-[MIT](https://opensource.org/licenses/MIT) license.
+[MIT](https://opensource.org/licenses/MIT/) license.
diff --git a/docs/building.md b/docs/building.md
new file mode 100644
index 00000000..a2d4a62c
--- /dev/null
+++ b/docs/building.md
@@ -0,0 +1,75 @@
+# How to build Tilde Friends
+
+> Disclaimer: this documentation has been written by a Linux user and has not been reviewed by other people on other platforms. The procedure may vary slightly depending on your operating system.
+
+Builds **on** Linux (`x86_64` and `aarch64`), MacOS, OpenBSD, and Haiku.
+
+Builds **for** all of those host platforms plus `mingw64`, iOS, and android.
+
+Dependencies:
+
+- `openssl` (`libssl-dev`, in debian-speak)
+
+Dependencies for Android:
+
+- TODO
+
+Dependencies for iOS:
+
+- TODO
+
+Dependencies for Windows:
+
+- TODO
+
+> All other dependencies are kept up to date as git submodules.
+
+1. Clone the repository with the submodules: `git clone --recursive https://dev.tildefriends.net/cory/tildefriends.git`
+
+2. Run `make -j $(nproc) debug` or `make -j $(nproc) release`
+
+> If you're unsure whether you should choose `debug` or `release`, stick to `release`.
+
+> `-j $(nproc)` will start a compiler for every CPU thread, which will dramatically reduce the time needed to compile Tilde Friends.
+
+An executable will be generated in a subdirectory of `out/`
+
+It's possible to build for Android, iOS, and Windows on Linux, if you have the right dependencies in the right places. Run `make -j $(nproc) windebug winrelease iosdebug-ipa iosrelease-ipa release-apk`
+
+To build in docker, `docker build .`
+
+On NixOS: TODO
+
+Now that you have a binary, head over to .
+
+## Troubleshooting
+
+### The compiler throws an error and I can't build the binary.
+
+Open `GNUMakefile` and edit the CFLAGS environment variable around line 50.
+
+For example given this error:
+
+```
+src/http.c: In function ‘tf_http_get_cookie’:
+src/http.c:1089:128: error: check of ‘name’ for NULL after already dereferencing it [-Werror=analyzer-deref-before-check]
+```
+
+Add:
+
+```diff
+CFLAGS += \
+ -std=gnu11 \
+ -Wall \
+ -Wextra \
+ -Wno-unused-parameter \
++ -Wno-analyzer-deref-before-check \
+ -MMD \
+ -MP \
+ -ffunction-sections \
+ -fdata-sections \
+ -fno-exceptions \
+ -g
+```
+
+Now the compiler will ignore this error and *should* continue building anyways.
diff --git a/docs/contributing.md b/docs/contributing.md
new file mode 100644
index 00000000..554c1436
--- /dev/null
+++ b/docs/contributing.md
@@ -0,0 +1,33 @@
+# How to contribute
+
+- Fork this repository
+
+- Clone your repository
+
+Alternatively, you can change the `origin` remote on your existing clone:
+
+`git remote set-url origin https://dev.tildefriends.net/YOUR_USERNAME/tildefriends.git`
+
+- Make your changes
+
+ - I want to edit C code !
+
+ - I want to edit JavaScript code !
+
+ - I want to write documentation !
+
+ Great! Before you do, have a look at the [documentation guidelines](guidelines/documentation-guidelines.md) to learn how to write consistent documentation.
+
+- Format your changes:
+
+If you've edited C code: run `make format`
+
+If you've edited JavaScript code or the documentation: run `npm run format`
+
+- Open a pull request
+
+TODO
+
+- Get your changes reviewed and merged
+
+TODO
diff --git a/docs/documentation.md b/docs/documentation.md
new file mode 100644
index 00000000..2fc7a476
--- /dev/null
+++ b/docs/documentation.md
@@ -0,0 +1,17 @@
+# Tilde Friends documentation
+
+## Building
+
+See .
+
+## Contibuting
+
+See .
+
+## FAQ / Troubleshooting
+
+See .
+
+## Guide
+
+See .
diff --git a/docs/faq.md b/docs/faq.md
new file mode 100644
index 00000000..67d2f29a
--- /dev/null
+++ b/docs/faq.md
@@ -0,0 +1,9 @@
+# Troubleshooting
+
+## I started tildefriends. Now what ?
+
+See .
+
+### The compiler throws an error and I can't build the binary.
+
+See .
diff --git a/docs/guide.md b/docs/guide.md
index f4aaa57c..f815f911 100644
--- a/docs/guide.md
+++ b/docs/guide.md
@@ -18,7 +18,7 @@ Above the terminal, an "Edit" link brings a visitor to the source code for the
current Tilde Friends application, which they can then edit, save as their own,
and run.
-# Architecture
+## Architecture
Tilde Friends is a C++ application with a JavaScript runtime that provides
restricted access to filesystem, network, and other system resources. The core
@@ -66,7 +66,7 @@ performance reasons to minimize the data size transferred between processes.
// Receive the above message and call the function.
core.register("onMessage", function(sender, message) {
- message.add(3, 4).then(x => terminal.print(x.toString()));
+ message.add(3, 4).then(x => terminal.print(x.toString()));
});
Finally, there is a core web interface that runs on the client's browser that
diff --git a/docs/guidelines/documentation-guidelines.md b/docs/guidelines/documentation-guidelines.md
new file mode 100644
index 00000000..1be46d20
--- /dev/null
+++ b/docs/guidelines/documentation-guidelines.md
@@ -0,0 +1,33 @@
+# Documentation guidelines
+
+This document defines the rules used to write documentation in order to make it more consistent.
+
+This documentation is a living document and so are it's rules; you are free to propose changes but in the meantime, please stick to them.
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119/).
+
+## File naming
+
+Files SHOULD be named using [kebab-case](https://www.freecodecamp.org/news/snake-case-vs-camel-case-vs-pascal-case-vs-kebab-case-whats-the-difference/#kebab-case).
+
+Their names should be meaningful and SHOULD not conflict with other files in other directories:
+
+> Example: this document is named `docs/guidelines/documentation-guidelines.md` instead of `docs/guidelines/documentation.md` because it could cause confusion with `docs/documentation.md`.
+
+## Documentation
+
+When writing documentation, the author should have in mind it's target audience: people with varying technical skills and backgrounds, fluency in peer-to-peer-specific terms and mental ability. The documentation should therefore be acessible and usefule to most people interested in building, using and contributing to Tilde Friends.
+
+### Terminology
+
+`Tilde Friends` refers to the projectas a whole. This can be abbreviated to `TF`.
+
+`tildefriends` refers to the program.
+
+### Style guide
+
+TODO
+
+## License
+
+As per the rest of the code in this repository, the documentation is shared under the [MIT](https://opensource.org/licenses/MIT/) license.
diff --git a/docs/running.md b/docs/running.md
new file mode 100644
index 00000000..ed790d57
--- /dev/null
+++ b/docs/running.md
@@ -0,0 +1,20 @@
+# Running Tilde Friends
+
+> Disclaimer: this documentation has been written by a Linux user and has not been reviewed by other people on other platforms. The procedure may vary slightly depending on your operating system.
+
+The binaries should appear at `out/debug/tildefriends` and `out/release/tildefriends`.
+
+For Android, iOS and Windows: TODO
+
+You can start the server by running `./out/debug/tildefriends` or `./out/release/tildefriends`.
+
+By default, running the built `tildefriends` executable will start a web server
+at . `tildefriends -h` lists further options.
+
+The first user to create an account and log in will be granted administrative
+privileges. Further administration can be done at
+.
+
+## How to use TF
+
+TODO