improve wording

as per review

docs/admin/Migration.md

@@ -19,7 +19,7 @@ breaking changes. **Please read them before running the migration.**
 
 ### New structure for Python packages
 
-The nominatim Python package has been split into nominatim-db and nominatim-api.
+The nominatim Python package has been split into `nominatim-db` and `nominatim-api`.
 Any imports need to be adapted accordingly.
 
 If you are running the Python frontend, change the server module from

docs/develop/Development-Environment.md

@@ -4,7 +4,7 @@ This chapter gives an overview how to set up Nominatim for development
 and how to run tests.
 
 !!! Important
-    This guide assumes that you develop under the latest version of Debain/Ubuntu.
+    This guide assumes you develop under the latest version of Debian/Ubuntu.
     You can of course also use your favourite distribution. You just might have
     to adapt the commands below slightly, in particular the commands for
     installing additional software.
@@ -41,8 +41,8 @@ It has the following additional requirements:
 For testing the Python search frontend, you need to install extra dependencies
 depending on your choice of webserver framework:
 
-* [httpx](https://www.python-httpx.org/) (starlette only)
-* [asgi-lifespan](https://github.com/florimondmanca/asgi-lifespan) (starlette only)
+* [httpx](https://www.python-httpx.org/) (Starlette only)
+* [asgi-lifespan](https://github.com/florimondmanca/asgi-lifespan) (Starlette only)
 
 The documentation is built with mkdocs:
 
@@ -106,12 +106,12 @@ be run in-place. The source directory features a special script
 but executes against the code in the source tree. For example:
 
 ```
-me@machine:~$ cd Nomiantim
-me@machine:~Nomiantim$ ./nominatim-cli.py --version
+me@machine:~$ cd Nominatim
+me@machine:~Nominatim$ ./nominatim-cli.py --version
 Nominatim version 4.4.99-1
 ```
 
-Make sure you have activated the virtual environment that holds all
+Make sure you have activated the virtual environment holding all
 necessary dependencies.
 
 ## Executing Tests
@@ -124,7 +124,14 @@ To run all tests, run make from the source root:
 make tests
 ```
 
-There are also goals for executing parts of the test suite: mypy, lint, pytest, bdd.
+There are also make targets for executing only parts of the test suite.
+For example to run linting only use:
+
+```sh
+make lint
+```
+
+The possible testing targets are: mypy, lint, pytest, bdd.
 
 For more information about the structure of the tests and how to change and
 extend the test suite, see the [Testing chapter](Testing.md).

docs/library/Getting-Started.md

@@ -18,12 +18,12 @@ To use the Nominatim library, you need access to a local Nominatim database.
 Follow the [installation](../admin/Installation.md) and
 [import](../admin/Import.md) instructions to set up your database.
 
-The Nominatim frontend library is contained in the 'nominatim-api' package.
+The Nominatim frontend library is contained in the Python package `nominatim-api`.
 To install the package from the source tree directly, run:
 
     pip install packaging/nominatim-api
 
-Usually, you would want to run this in a virtual environment.
+Usually you would want to run this in a virtual environment.
 
 ### A simple search example
 

packaging/nominatim-api/README.md

@@ -4,8 +4,8 @@ Nominatim is a tool to search OpenStreetMap data
 by name and address (geocoding) and to generate synthetic addresses of
 OSM points (reverse geocoding).
 
-This module implements the library for searching in a Nominatim database
-imported with the 'nominatim-db' package.
+This module implements the library for searching a Nominatim database
+imported with the [`nominatim-db`](https://pypi.org/project/nominatim-db/) package.
 
 ## Installation
 
@@ -15,7 +15,7 @@ To install the Nominatim API from pypi, run:
 
 ## Running a Nominatim server
 
-You need falcon or starlette to run Nominatim as a service, as well as
+You need Falcon or Starlette to run Nominatim as a service, as well as
 an ASGI-capable server like uvicorn. To install them from pypi run:
 
     pip install falcon uvicorn
@@ -28,10 +28,10 @@ package. Go to the project directory, then run uvicorn as:
 ## Documentation
 
 The full documentation for the Nominatim library can be found at:
-https://nominatim.org/release-docs/develop/library/Getting-Started/
+https://nominatim.org/release-docs/latest/library/Getting-Started/
 
 The v1 API of the server is documented at:
-https://nominatim.org/release-docs/develop/api/Overview/
+https://nominatim.org/release-docs/latest/api/Overview/
 
 ## License
 

packaging/nominatim-api/pyproject.toml

@@ -24,7 +24,9 @@ dynamic = ["version"]
 
 [project.urls]
 Homepage = "https://nominatim.org"
+Documentation = "https://nominatim.org/release-docs/latest/"
 Issues = "https://github.com/osm-search/Nominatim/issues"
+Repository = "https://github.com/osm-search/Nominatim"
 
 [build-system]
 requires = ["hatchling"]

packaging/nominatim-db/README.md

@@ -12,9 +12,9 @@ command-line tool for importing and maintaining the database.
 ### Prerequisites
 
 Nominatim requires [osm2pgsql](https://osm2pgsql.org/) (>=1.8) for reading
-OSM data and [PostgreSQL](https://www.postgresql.org/) to store the data.
+OSM data and [PostgreSQL](https://www.postgresql.org/) (>=9.6) to store the data.
 
-On Ubuntu (>=23.04) and Debian (using backports), you can install them with:
+On Ubuntu (>=23.04) and Debian (when using backports), you can install them with:
 
     sudo apt-get install osm2pgsql postgresql-postgis
 
@@ -30,21 +30,24 @@ To install Nominatim from pypi, run:
 First create a project directory for your new Nominatim database, which
 is the space for additional configuration and customization:
 
-    mkdir planet-project
+    mkdir nominatim-project
+
+Make sure you run all nominatim commands from within the project directory:
+
+    cd nominatim-project
 
 Download an appropriate data extract, for example from
 [Geofabrik](https://download.geofabrik.de/) and import the file:
 
     nominatim import --osm-file <downlaoded-osm-data.pbf>
 
-You will need to install the 'nominatim-api' package to query the
-database.
+You will need to install the [`nominatim-api`](https://pypi.org/project/nominatim-api/)
+package to query the database.
 
 ## Documentation
 
-The documentation of the latest development version is in the
-`docs/` subdirectory. A HTML version can be found at
-https://nominatim.org/release-docs/develop/ .
+A HTML version of the documentation can be found at
+https://nominatim.org/release-docs/latest/ .
 
 ## License
 

packaging/nominatim-db/pyproject.toml

@@ -26,8 +26,9 @@ dynamic = ["version"]
 
 [project.urls]
 Homepage = "https://nominatim.org"
-Issues = "https://github.com/osm-search/Nominatim/issues"
 Documentation = "https://nominatim.org/release-docs/latest/"
+Issues = "https://github.com/osm-search/Nominatim/issues"
+Repository = "https://github.com/osm-search/Nominatim"
 
 [build-system]
 requires = ["hatchling"]

vagrant/Install-on-Ubuntu-24.sh

@@ -67,7 +67,7 @@ fi                                 #DOCS:
 # ---------------------
 #
 # Tune the postgresql configuration, which is located in 
-# `/etc/postgresql/14/main/postgresql.conf`. See section *Tuning the PostgreSQL database*
+# `/etc/postgresql/16/main/postgresql.conf`. See section *Tuning the PostgreSQL database*
 # in [the installation page](../admin/Installation.md#tuning-the-postgresql-database)
 # for the parameters to change.
 #
@@ -124,9 +124,11 @@ fi                                 #DOCS:
 # Nominatim is now ready to use. The nominatim binary is available at
 # `$USERHOME/venv/bin/nominatim`. If you want to have 'nominatim' in your
 # path, simply activate the virtual environment:
-
-
-
+#
+#DOCS:```sh
+# . $USERHOME/nominatim-venv/bin/activate
+#DOCS:```
+#
 # You can continue with
 # [importing a database from OSM data](../admin/Import.md). If you want to set up
 # the API frontend first, continue reading.
@@ -135,8 +137,8 @@ fi                                 #DOCS:
 # ==============================
 #
 # The Python frontend is contained in the nominatim-api package. To run
-# the API as a webservice, you also need falcon with uvicorn/gunicorn to
-# serve the API.
+# the API as a webservice, you also need falcon with uvicorn to serve the API.
+# It is generally recommended to run falcon/uvicorn on top of gunicorn.
 #
 # To install all packages, run: