Improve the documentation

README.md

@@ -33,35 +33,19 @@ limitations under the License.
 
 ## 📖 How do I use Apache Baremaps?
 
-You can find the documentation on the project's [website](https://baremaps.apache.org/). The following pages showcase the main uses of Apache Baremaps.
-
-- The [OpenStreetMap](https://baremaps.apache.org/documentation/examples/import-osm-into-postgis) example is a good introduction to Baremaps, it shows how to produce high resolution vector tiles.
-- The [NaturalEarth](https://baremaps.apache.org/documentation/examples/import-naturalearth-into-postgis) example shows how to produce low resolution vector tiles.
-- The [Contour](https://baremaps.apache.org/documentation/examples/import-contour-into-postgis) example shows how to produce contour lines from a digital elevation model.
-- The [IP to location](https://baremaps.apache.org/documentation/examples/ip-to-location) example shows how to create and serve an IP to location service in a simple web application.
-- The [Geocoding](https://baremaps.apache.org/documentation/examples/geocoding) example shows how to create and serve a geocoding service in a simple web application.
+You can find a [getting started](https://baremaps.apache.org/documentation/getting-started/) and [additional examples] on the project's [website](https://baremaps.apache.org/).
 
 ## 👩‍💻 How do I contribute?
 
-There are many places where you can contribute to Apache Baremaps such as the code, the documentation, the website or the examples.
-
-The official documentation is located in a separate [repository](https://github.com/apache/incubator-baremaps-site).
-
-If you want to contribute to the code you can refer to the following developer guides available in the documentation.
-
-- [Project structure](https://baremaps.apache.org/documentation/developer-manual/project-structure)
-- [How to build with Maven](https://baremaps.apache.org/documentation/developer-manual/how-to-build-with-maven)
-- [Set up in IntelliJ IDEA](https://baremaps.apache.org/documentation/developer-manual/setup-in-intellij)
-- [Geocoder](https://baremaps.apache.org/documentation/developer-manual/geocoder)
-- [IP to location](https://baremaps.apache.org/documentation/developer-manual/ip-to-location)
-- [Basemap](https://baremaps.apache.org/documentation/developer-manual/basemap)
+There are many places where you can contribute to Apache Baremaps and your contributions are more than welcome.
 
-You can also contribute in the following ways.
+The [developer manual](https://baremaps.apache.org/documentation/additional-examples/) provides a good starting point on how to build and run the project from source.
 
+You can contribute in the following ways:
 - Improve the code: Report [a bug or submit a feature request](https://github.com/apache/incubator-baremaps/issues), or [submit a pull request](https://github.com/apache/incubator-baremaps/pulls) in the [incubator-baremaps](https://github.com/apache/incubator-baremaps/) repository.
 - Improve the documentation: Report [documentation issue](https://github.com/apache/incubator-baremaps-site/issues) or [submit a pull request](https://github.com/apache/incubator-baremaps-site/pulls) in the [incubator-baremaps-site](https://github.com/apache/incubator-baremaps-site/) repository.
-- [Join the mailing list](https://lists.apache.org/[email protected]): Initiate or participate in project discussions on the mailing list
-- Write a post: Write a post to share your use cases and experiences with Apache Baremaps
+- [Join the mailing list](https://lists.apache.org/[email protected]): Initiate or participate in project discussions on the mailing list.
+- Write a post: Write a post to share your use cases and experiences with Apache Baremaps.
 
 Finally, check out [CONTRIBUTING](CONTRIBUTING.md) and [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md).
 

basemap/README.md

@@ -34,17 +34,35 @@ A PostgreSQL database with the PostGIS extension should be accessible with the f
 jdbc:postgresql://localhost:5432/baremaps?user=baremaps&password=baremaps
 ```
 
+If you plan on importing the whole planet, you will need a powerful machine with a lot of storage. You may also want to modify the `postgresql.conf` file to increase some of the default settings.
+
+```
+work_mem = 4GB
+shared_buffers = 4GB
+maintenance_work_mem = 16GB
+autovacuum_work_mem = 4GB
+max_worker_processes = 16
+max_parallel_workers_per_gather = 8
+max_parallel_workers = 16
+wal_level = minimal
+checkpoint_timeout = 10min
+max_wal_size = 20GB
+min_wal_size = 80MB
+checkpoint_completion_target = 0.9
+max_wal_senders = 0
+```
+
 ## Importing the data
 
-Assuming that the necessary requirements have been installed, the database can be populated with the following command.
+Assuming that the necessary requirements have been installed, the database can be populated with the following command. The import workflow will download openstreetmap (osm.pbf) and other data sources into the database.
 
 ```
 baremaps workflow execute --file import.js
 ```
 
 ## Updating the data
 
-The data can be updated with the following command. The update workflow will download the latest changes from the OpenStreetMap API and apply them to the database.
+The data can periodically be updated with the following command. The update workflow will download the latest changes from OpenStreetMap (osc.xml) and apply them to the database.
 
 ```
 baremaps workflow execute --file update.js