doc: slight reorganization and consistency adjustments

3 files changed, 26 insertions, 32 deletions

diff --git a/doc/dev/index.rst b/doc/dev/index.rst
index 9ee38b1f..1f6dc1da 100644
--- a/doc/dev/index.rst
+++ b/doc/dev/index.rst
@@ -2,10 +2,10 @@
 
 .. warning::
 
-   **This documentation is intended to help with advanced fine-tuning of Knot
-   Resolver!** If you are looking for help with day-to-day use without the need to
-   involve yourself with the Lua programming language, please see the
-   `user documentation <../index.html>`_.
+   **This documentation is intended to help with advanced fine-tuning and
+   development of Knot Resolver!** If you are looking for help with day-to-day
+   use without the need to involve yourself with C and/or Lua programming
+   languages, please see the `user documentation <../index.html>`_.
 
 #####################################
 Knot Resolver developer documentation
@@ -14,18 +14,19 @@ Knot Resolver developer documentation
 Welcome to Knot Resolver's documentation for developers and advanced users!
 
 .. toctree::
-   :caption: Building for sources
+   :caption: Building from sources
    :name: build-chapter
    :maxdepth: 1
 
    build
+   manager-dev-env
 
 .. toctree::
-   :caption: Development Guides
-   :name: development-guides
+   :caption: Architecture
+   :name: architecture-chapter
    :maxdepth: 1
 
-   manager-dev-env
+   architecture
    manager-dev-code
 
 .. toctree::
@@ -53,13 +54,6 @@ Welcome to Knot Resolver's documentation for developers and advanced users!
    logging_api
 
 .. toctree::
-   :caption: Architecture
-   :name: architecture-chapter
-   :maxdepth: 1
-
-   architecture
-
-.. toctree::
    :caption: Infrastructure
    :name: infra-chapter
    :maxdepth: 1
diff --git a/doc/dev/manager-dev-code.rst b/doc/dev/manager-dev-code.rst
index 4a0e56ba..c211d536 100644
--- a/doc/dev/manager-dev-code.rst
+++ b/doc/dev/manager-dev-code.rst
@@ -2,9 +2,9 @@
 
 .. _manager-dev-code:
 
-****************************
-The manager's code structure
-****************************
+**********************
+Manager code structure
+**********************
 
 The manager's code is split into several distinct logical components:
 
@@ -31,21 +31,21 @@ The supervisord subprocess controller actually extends supervisord with new func
 
 We want to have the Manager restarted if it fails, so that one mishandled API request can't bring everything down. We want the subprocess controllers to control the execution of the Manager and restart it, if needed. Therefore, there is a circular dependency. To solve it, the subprocess controller implementations are allowed to ``exec()`` into anything else while starting. To give an example of how the startup works with supervisord:
 
-1. *the server* loads the config, initiates *the manager* and *the supervisord subprocess controller*
-2. *the supervisord subprocess controller* detects, that there is no supervisord running at the moment, generates new supervisord config and exec's supervisord
-3. supervisord starts, loads its config and starts *the server* again
-4. *the server* loads the config, initiates *the manager* and *the supervisord subprocess controller*
-5. *the supervisord subprocess controller* detects, that there is a supervisord instance running, generates new config for it and reloads it
+1. *the server* loads the configuration, initiates *the manager* and *the supervisord subprocess controller*
+2. *the supervisord subprocess controller* detects, that there is no supervisord running at the moment, generates new supervisord configuration and exec's supervisord
+3. supervisord starts, loads its configuration and starts *the server* again
+4. *the server* loads the configuration, initiates *the manager* and *the supervisord subprocess controller*
+5. *the supervisord subprocess controller* detects, that there is a supervisord instance running, generates new configuration for it and reloads it
 6. *the manager* starts new workers based on the initial configuration
 7. *the server* makes it's API available to use and the Manager is fully running
 
 
-Processing of config change requests
-====================================
+Processing of configuration change requests
+===========================================
 
 1. a change request is received by *the server*
 2. the raw text input is parsed and verified into a configuration object using *the datamodel*
 3. *the manager* is asked to apply new configuration
-4. *the manager* starts a canary process with the new config (Lua config generated from the configration object), monitoring for failures
+4. *the manager* starts a canary ``kresd`` process with the new configuration (Lua code generated from the configration object), monitoring for failures
 5. *the manager* restarts all ``kresd`` instances one by one
 6. *the server* returns a success
diff --git a/doc/dev/manager-dev-env.rst b/doc/dev/manager-dev-env.rst
index 845cfd89..430fbd23 100644
--- a/doc/dev/manager-dev-env.rst
+++ b/doc/dev/manager-dev-env.rst
@@ -2,9 +2,9 @@
 
 .. _manager-dev-env:
 
-*************************************
-The manager's development environment
-*************************************
+*******************************
+Manager development environment
+*******************************
 
 In this guide, we will setup a development environment and discuss tooling.
 
@@ -44,13 +44,13 @@ Running the manager from source for the first time
 
    As mentioned above it is recommended to use ``pyenv`` to manage other Python versions.
    Then poetry needs to be told where to look for that version of Python, e.g.:
-   
+
    .. code-block:: bash
-      
+
       $ poetry env use ~/.pyenv/versions/3.12.1/bin/python3.12
 
 4. Run ``poetry install --all-extras`` to install all dependencies including all optional ones (--all-extras flag), in a newly created virtual environment.
-   All dependencies can be seen in ``pyproject.toml``. 
+   All dependencies can be seen in ``pyproject.toml``.
 5. Use ``./poe run`` to run the manager in development mode (Ctrl+C to exit).
    The manager is started with the configuration located in ``manager/etc/knot-resolver/config.dev.yaml``.