More FAQs rewritten and/or integrated into the documentation

docs/docs/get-started/_category_.json

@@ -1,8 +1,8 @@
 {
-  "label": "Tutorial",
+  "label": "Guides",
   "position": 6,
   "link": {
     "type": "generated-index",
-    "description": "In-depth details about how to use the various elements of the Knowledge Engine"
+    "description": "In-depth details about how to use the various elements of the Knowledge Engine."
   }
 }

docs/docs/get-started/knowledge-directory.md

@@ -0,0 +1,13 @@
+---
+sidebar_position: 4
+---
+# Starting a Knowledge Directory
+This page describes how to setup a Knowledge Directory.
+
+You can start the Knowledge Directory on ports 8080 with the available JAR:
+```bash
+cd knowledge-directory/target/
+
+java -Dorg.slf4j.simpleLogger.logFile=kd.log -cp "knowledge-directory-1.2.5.jar:dependency/*" eu.knowledge.engine.knowledgedirectory.Main 8080
+```
+You can of course run the Knowledge Directory on another port by replacing 8080 by your preferred port number.

docs/docs/get-started/knowledge-interactions.md

@@ -3,7 +3,8 @@
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-# Knowledge Interactions
+# Using Knowledge Interactions
+This page describes how to register and execute Knowledge Interactions.
 
 ## How to instantiate a Knowledge Interaction?
 <Tabs groupId="tke-usage">

docs/docs/get-started/smart-connector.md

@@ -5,9 +5,42 @@ sidebar_position: 6
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-# Smart Connectors
+# Connecting to a Knowledge Network
+This page describes how to connect to an (existing) Knowledge Network using a Smart Connector.
+
+To connect to a Knowledge Network, you need a Knowledge Engine Runtime (KER).
+Every KER in distributed mode consists of two APIs: [Knowledge Engine Developer REST API](https://github.com/TNO/knowledge-engine/blob/1.2.5/smart-connector-rest-server/src/main/resources/openapi-sc.yaml) and the [Inter-Knowledge Engine Runtime API](https://github.com/TNO/knowledge-engine/blob/1.2.5/smart-connector/src/main/resources/openapi-inter-ker.yaml).
+The former is started on port `8280` by default, and you use this API to register your Knowledge Base and Knowledge Interactions.
+The latter API is meant for internal communication between KERs and you do not need to use it yourself.
+However, you do need to make sure this API is reachable for other KERs in the Knowledge Network.
+By default, this API is available on port 8081, but sometimes you need to change this port using the `KE_RUNTIME_PORT` environment variable.
+Make sure the latter API of your KER is accessible from the internet and configure its URL when starting the KER with the `KE_RUNTIME_EXPOSED_URL` environment variable.
+To set this up correctly, you typically install a reverse proxy like NGINX and open the correct ports in the firewall of the server.
+For this you need to contact the administrator of the server you are using.
+A KER starts in distributed mode when it detects the `KD_URL` environment variable.
+This variable points to the Knowledge Directory of the Knowledge Network.
+You can configure it using environment variables `KD_URL=<knowledge-direcotry-url>`.
+If the Knowledge Directory is protected using Basic Authentication, you can add the credentials to the KD_URL as described [here](https://stackoverflow.com/a/50528734).
+
+
+
+To connect to a network, the following steps are required:
+* Get access to the Knowledge Engine Runtime (KER) you want to connect to
+* Start a Knowledge Engine Runtime (KER) on your computer
+* Register your Knowledge Base via the REST Developer API
+* [Register your Knowledge Interactions via the REST Developer API](./knowledge-interactions.md)
+
+## Getting access to the Knowledge Engine Runtime
+To get access to the Knowledge Engine Runtime you want to connect to, you will need its URL.
+You can test whether you have access to its REST Developer API by activating its `GET /sc` operation via the browser with a URL like: `<ker-url>/sc`
+If the KER is protected with Basic Authentication, your browser might ask you for credentials. 
+This operation returns JSON with all the Knowledge Bases that are registered with that Knowledge Engine Runtime.
+An empty list indicates that no Knowledge Bases are registered with this Knowledge Engine Runtime.
+If you run a Knowledge Engine Runtime on your own computer, then the URL is typically `http://localhost:8280`.
+
+## How to start a Smart Connector?
+> *Before starting a Smart Connector, please ensure that there is a Knowledge Directory available to connect to.*
 
-## How to instantiate a Smart Connector?
 <Tabs groupId="tke-usage">
 <TabItem value="java" label="Java">
 
@@ -31,9 +64,6 @@ java -Dorg.slf4j.simpleLogger.logFile=ke.log -cp "smart-connector-rest-dist-1.2.
 </TabItem>
 </Tabs>
 
-
-## How to add a Smart Connector?
-
 ## How to remove a Smart Connector?
 
 ## How to renew the lease of a Smart Connector?