docs: new documentation

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 <http://localhost:12345/>. `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
-<http://localhost:12345/~core/admin/>.
-
 ## Documentation
 
-Docs are a work in progress:
-<https://www.tildefriends.net/~cory/wiki/#test-wiki/tf-app-quick-reference>.
+Docs are a work in progress in the `docs` folder and in Tilde Friends: <https://www.tildefriends.net/~cory/wiki/#test-wiki/tf-app-quick-reference>.
 
 ## 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.

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 <running.md>.
+
+## 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.

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

docs/documentation.md

@@ -0,0 +1,17 @@
+# Tilde Friends documentation
+
+## Building
+
+See <building.md>.
+
+## Contibuting
+
+See <contributing.md>.
+
+## FAQ / Troubleshooting
+
+See <faq.md>.
+
+## Guide
+
+See <guide.md>.

docs/faq.md

@@ -0,0 +1,9 @@
+# Troubleshooting
+
+## I started tildefriends. Now what ?
+
+See <running.md>.
+
+### The compiler throws an error and I can't build the binary.
+
+See <building.md>.

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

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.

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 <http://localhost:12345/>. `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
+<http://localhost:12345/~core/admin/>.
+
+## How to use TF
+
+TODO