[doc] massaging

Author: knopers8

README.md

@@ -53,19 +53,22 @@ There are two ways of interacting with AliECS:
 
 ### I want to develop AliECS
 
-:hammer_and_wrench: [Building instructions](https://alice-flp.docs.cern.ch/aliecs/building/)
-    
-:arrow_right: [Running instructions](https://alice-flp.docs.cern.ch/aliecs/running/)
-
-TODO CONTRIBUTING.md
+:hammer_and_wrench: Welcome to the team, please head to [contributing instructions](/docs/CONTRIBUTING.md)
 
 ### I want to receive updates about environments or services controlled by AliECS
 
-:book: Learn more about the [kafka event service](docs/kafka.md)
+:pager: Learn more about the [kafka event service](/docs/kafka.md)
+
+### I want my application to send requests to AliECS
+
+:scroll: See the API docs of AliECS components:
+- [AliECS core gRPC server](/docs/apidocs_aliecs.md)
+- [apricot gRPC server](/docs/apidocs_apricot.md)
+- [apricot HTTP server](/apricot/docs/apricot_http_service.md)
 
-### I want my service to communicate with AliECS
+### I want my service to be sent requests by AliECS
 
-:book: Learn more about the [plugin system](TODO)
+:electric_plug: Learn more about the [plugin system](/core/integration/README.md)
 
 ## Table of Contents
 
@@ -156,7 +159,7 @@ TODO CONTRIBUTING.md
       * [Using Kafka debug tools](/docs/kafka.md#using-kafka-debug-tools)
 
 * Developer documentation
-  * [Contributing](CONTRIBUTING.md)
+  * [Contributing](/docs/CONTRIBUTING.md)
   * [Package pkg.go.dev documentation](https://pkg.go.dev/github.com/AliceO2Group/Control)
   * [Building AliECS](/docs/building.md#building-aliecs)
     * [Overview](/docs/building.md#overview)
@@ -166,7 +169,8 @@ TODO CONTRIBUTING.md
       * [Clone and build (Go components only)](/docs/building.md#clone-and-build-go-components-only)
   * [Makefile reference](/docs/makefile_reference.md)
   * [Component Configuration](/docs/handbook/appconfiguration.md#component-configuration)
-    * [Connectivity to controlled nodes](/docs/handbook/appconfiguration.md#connectivity-to-controlled-nodes)
+    * [Apache Mesos](/docs/handbook/appconfiguration.md#apache-mesos)
+      * [Connectivity to controlled nodes](/docs/handbook/appconfiguration.md#connectivity-to-controlled-nodes)
   * [Running AliECS as a developer](/docs/running.md#running-aliecs-as-a-developer)
     * [Running the AliECS core](/docs/running.md#running-the-aliecs-core)
   * [Running AliECS in production](/docs/running.md#running-aliecs-in-production)

docs/building.md

@@ -12,7 +12,6 @@ AliECS consists of:
 * coconut - Go, runs locally or wherever you like and connects to core
 * process control plugin + library (OCC) - C++, runs throughout the cluster linked by user processes
 * peanut - Go, local debugging tool
-* walnut - Go, local workflow conversion tool
 
 ## Building with aliBuild
 

docs/handbook/appconfiguration.md

@@ -1,6 +1,10 @@
 # Component Configuration
 
-## Connectivity to controlled nodes
+## Apache Mesos
+
+Apache Mesos is installed as a part of the FLP Suite.
+
+### Connectivity to controlled nodes
 
 ECS relies on Mesos to know the state of the controlled nodes.
 Thus, losing connection to a Mesos slave can be treated as a node being down or unresponsive.
@@ -9,4 +13,4 @@ Then, the environment is transitioned to ERROR.
 
 Mesos slave health check can be configured with `MESOS_MAX_AGENT_PING_TIMEOUTS` (`--max_agent_ping_timeouts`) and `MESOS_AGENT_PING_TIMEOUT` (`--agent_ping_timeout`) parameters for Mesos.
 Effectively, the factor of the two parameters is the time needed to consider a slave/agent as lost.
-Please refer to Mesos documentation for more details.
+Please refer to [Mesos documentation](https://mesos.apache.org/documentation/latest/) for more details.

docs/running.md

@@ -1,14 +1,14 @@
 # Running AliECS as a developer
 
-
 > **WARNING**: The running instructions described in this page are **for development purposes only**. Users interested in deploying, running and controlling O²/FLP software or their own software with AliECS should refer to the O²/FLP Suite instructions instead.
 
-
 ## Running the AliECS core
 
 This part assumes you have already set up the Go environment, fetched the sources and built all AliECS Go components.
 
-The recommended way to set up a Mesos cluster is by performing a complete deployment of the O²/FLP Suite with `o2-flp-setup`. The AliECS core on the head node should be stopped (`systemctl stop o2-aliecs-core`) and your own AliECS core should be made to point to the head node.
+The recommended way to set up a Mesos cluster is by performing a complete deployment of the O²/FLP Suite with `o2-flp-setup`.
+The AliECS core on the head node should be stopped (`systemctl stop o2-aliecs-core`) and your own AliECS core should be made to point to the head node.
+Typically, it can be done by replacing the AliECS core binary on the head node with your own and restarting the `o2-aliecs-core` systemd service.
 
 The following example flags assume a remote head node `centosvmtest`, the use of the default `settings.yaml` file, very verbose output, verbose workflow dumps on every workflow deployment, and the executor having been copied (`scp`) to `/opt/o2control-executor` on all controlled nodes: