Merge branch '10-initial-documentation' into 'main'

Resolve "Initial Documentation"

Closes #10

See merge request !10

doc/README.md

@@ -14,7 +14,7 @@ It aims to be a complete solution including features like:
 
 ## About this Documentation
 
-Documentation is structured in two parts: User documentation and Development documentation. If you just want to use the software, the former is for you.
+Documentation is structured in two parts: User documentation and Development documentation. If you just want to use the software, [the former](./user/index.md) is for you.
 Furthermore, we acknowledge divio's [documentation system](https://docs.divio.com/documentation-system/), consisting of:
 * learning oriented **tutorials ◆**,
 * problem oriented **how-to guides ◇**,

doc/user/howto_basic.md

@@ -7,4 +7,21 @@ SPDX-License-Identifier: AGPL-3.0-only
 This how-to helps you set up Suggestible using your own data.
 
 If you want to just try out Suggestible with some sample data at first, we recommend to try the [introductory tutorial](tutorial_basic.md) first.
-If you don't have a compiled version of Suggestible yet, follow our [build how-to](howto_build.md).
\ No newline at end of file
+If you don't have a compiled version of Suggestible yet, follow our [build how-to](howto_build.md).
+## Place Training Data
+To use Suggestible, you need a csv file named `data.csv` with training data to learn suggestions from. Suggestible is looking for it in whichever folder you are running Suggestible from.
+Currently, Suggestible needs the sixth column of the csv to contain the actual search queries. This is subject to change.
+
+Here is an example of what your file could look like:
+```csv
+"time","referer","request_time","focus","locale","query"
+2024-04-01 08:35:42.000 +0200,,,web,en,what is love?
+```
+
+## Configuring Suggestible
+Currently, no configuration is possible. This will change soon.
+
+## Running Suggestible
+When you run Suggestible it will look for a data.csv in your current working directory, read it and then start a web server on port 80.
+
+It exposes an [OpenSearch](https://github.com/dewitt/opensearch/blob/master/mediawiki/Specifications/OpenSearch/Extensions/Suggestions/1.1/Draft%201.wiki) compliant suggestions api at `/?q={searchTerms}`.
\ No newline at end of file

doc/user/howto_build.md

@@ -4,3 +4,53 @@ SPDX-FileCopyrightText: 2024 Phil Höfer <phil@suma-ev.de>
 SPDX-License-Identifier: AGPL-3.0-only
 -->
 # Building Suggestible ◇
+
+Building Suggestible is easy. Just start by making sure all dependencies are installed on your system, then start the build using the included makefile.
+
+## Prerequisites
+
+1. **Rust and Cargo**: Ensure Rust and Cargo are installed. You can install them using [rustup](https://rustup.rs/).
+
+    ```sh
+    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+    ```
+
+2. **mdBook**: Install mdBook using Cargo. MdBook is used to generate Suggestible's documentation.
+
+    ```sh
+    cargo install mdbook
+    ```
+
+## Building Suggestible
+
+1. **Navigate to the Project Directory**: Open your terminal and change to the project directory.
+
+    ```sh
+    cd /path/to/suggestible
+    ```
+
+2. **Build Suggestible**: Use make to compile the project.
+
+    ```sh
+    make release
+    ```
+
+    This will create an optimized build in the `target/release` directory.
+
+## Using Suggestible
+
+To see if everything went well and Suggestible runs you can try running it through Cargo with:
+```sh
+cargo run --release
+```
+For further intructions on how to use Suggestible in your production setting refer to our [usage how-to](howto_basic.md).
+
+## Building the Documentation
+
+To build this documentation, simply call `make` with the `doc` target:
+
+```sh
+make doc
+```
+
+This will generate the documentation in the `book` directory.
\ No newline at end of file