diff --git a/data/copyright.html b/data/copyright.html
index 965373bb2b..6c1c5deb86 100644
--- a/data/copyright.html
+++ b/data/copyright.html
@@ -301,7 +301,7 @@
       &copy; 1998&ndash;2003 James Kass; Shareware</li>
   </ul>
 
-<p>We also use these icons on the map:</p>
+<p id="icons">We also use these icons on the map:</p>
 
 <ul class="license-list">
   <li><a href="https://github.com/google/material-design-icons">Material Design Icons</a><br>
diff --git a/data/replaced_tags.txt b/data/replaced_tags.txt
index e0b8f33dc7..3c76e8f527 100644
--- a/data/replaced_tags.txt
+++ b/data/replaced_tags.txt
@@ -1,3 +1,21 @@
+# Sometimes a few different OSM tags are used interchangeably to map the same feature.
+# Or there might be some difference between tags usage but it doesn't matter in the context of Organic Maps.
+# For such cases we can rename/replace/merge one tag into the other to avoid duplicating style rules, translations, etc.
+#
+# E.g.
+#      shop=ice_cream : amenity=ice_cream
+# means that all shop=ice_cream tags will be converted into amenity=ice_cream during maps generation,
+# so there will be no shop=ice_cream in MWM map files at all.
+#
+# In the following example
+#      vending=parcel_pickup : amenity=parcel_locker | u
+# the 'u' flag means update/replace existing tag with the same key (if any),
+# e.g. for a feature {amenity=vending_machine, vending=parcel_pickup}
+# the above rule will produce {amenity=vending_machine, amenity=parcel_locker},
+# but we don't need two "amenity" keys here,
+# so adding the 'u' updates value of the existing amenity=vending_machine tag with "parcel_locker"
+# and the result becomes {amenity=parcel_locker}.
+#
 # Format:
 # <replacement>           ::= <original tag> ' : ' <replacement tags list> [' | ' flag]
 # <original tag>          ::= <tag>
@@ -6,9 +24,6 @@
 # <key>                   ::= string without spaces, '=', ',', '|' symbols
 # <value>                 ::= string without spaces, '=', ',', '|' symbols
 # <flag>                  ::= control flag {'u'}
-#     'u' - update/replace existing tag with the same key, if any, e.g. for a feature {amenity=vending, vending=parcel}
-#      we'd like to convert vending=parcel into amenity=parcel, so we'll end up with {amenity=vending, amenity=parcel},
-#      but we don't need amenity=vending, 'u' replaces it with a newly converted amenity=parcel.
 
 atm=yes : amenity=atm
 bench=yes : amenity=bench
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index 69559ad280..795977a44e 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -1,10 +1,10 @@
 # Contributing
 
-Thank you for your interest in contributing to Organic Maps!
+Thank you for your interest in contributing to Organic Maps (OM)!
 
 ## How Can I Contribute?
 
-There are many ways to contribute.
+There are many ways to contribute and OM needs a variety of talents: programmers, graphic designers, translators, UI/UX experts, etc.
 
 ### Donate
 
@@ -16,8 +16,8 @@ The simplest way to contribute is to [submit an issue](https://github.com/organi
 Please give developers as much information as possible: OS and application versions,
 list of actions leading to a bug, a log file produced by the app.
 
-When using the Organic Maps app on a device, use the built-in "Report a bug" option:
-it creates a new e-mail with a log file attached. Your issue will be processed much
+When using the OM app on a device, use the built-in "Report a bug" option:
+on Android it creates a new e-mail with a log file attached. Your issue will be processed much
 faster if you send it to bugs@organicmaps.app.
 
 ### Feature Requests
@@ -26,34 +26,32 @@ If you have some ideas or want to request a new feature, please [start a discuss
 
 ### Translations
 
-If you want to improve app translations or add more search synonyms, please update [strings.txt](https://github.com/organicmaps/organicmaps/blob/master/data/strings/strings.txt) file, run `./tools/unix/generate_localizations.sh` and create a [Pull Request](#pull-requests).
+OM is available in 35 languages already, but some of them are incomplete and existing translations need regular updates as the app evolves.
+See [translations instructions](TRANSLATIONS.md) for details.
 
-Use `./tools/python/strings/google_translate.py` to generate initial strings for all languages:
+### Map styling and icons
 
-```bash
-cd tools/python/strings
-python3 -m venv venv
-source venv/bin/activate
-pip3 install -r requirements.txt
-```
+We strive to have a functional, cohesive and pleasant to the eye map rendering style.
+There is always something to improve, add new map features, fine tune colors palette etc.
+And every time we add a new map feature/POI we need a good and free-to-use icon.
 
-```bash
-./google_translate.py "Hello"
-```
+See [styles and icons instructions](STYLES.md) for details.
 
 ### Code Contributions
 
-Please follow instructions in [INSTALL.md](INSTALL.md) to set up your development environment.
-Create and submit a [Pull Request](#pull-requests) with your changes.
+Please follow instructions in [INSTALL.md](INSTALL.md) to set up your development environment
+and check the [developer's guidelines](#developers-guidelines).
+You will find a list of issues for new contributors [here](https://github.com/organicmaps/organicmaps/labels/Good%20first%20issue) to help you get started with simple tasks.
 
-## Process
+## Submitting your changes
 
-### Pull Requests
+All contributions to Organic Maps repository should be submitted via
+[Github pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork)
+and signed-off with the [Developers Certificate of Origin](#legal-requirements).
 
-All contributions to Organic Maps source code should be submitted via github pull requests.
-Each pull request is reviewed by OMaps maintainers, to ensure consistent code style
-and quality. Sometimes the review process even for smallest commits can be
-very thorough. Please follow [the developer guidelines](#guidelines).
+Each pull request is reviewed by OM maintainers to ensure its quality.
+Sometimes the review process even for smallest commits can be
+very thorough.
 
 ### Legal Requirements
 
@@ -77,11 +75,11 @@ Git has a flag that can sign a commit for you. An example using it is:
 Use your real name or on some rare cases a company email address, but we
 disallow pseudonyms or anonymous contributions.
 
-### Code of Conduct
+## Code of Conduct
 
-The Organic Maps community abides by the [CNCF code of conduct](CODE_OF_CONDUCT).
+The OM community abides by the [CNCF code of conduct](CODE_OF_CONDUCT.md).
 
-### Guidelines
+## Developer's Guidelines
 
 - [C++ Style Guide](CPP_STYLE.md).
 - [Objective-C Style Guide](OBJC_STYLE.md).
@@ -90,6 +88,6 @@ The Organic Maps community abides by the [CNCF code of conduct](CODE_OF_CONDUCT)
 
 ## Questions?
 
-For any questions about developing Organic Maps and relevant services -
+For any questions about developing OM and relevant services -
 virtually about anything related, please [contact us](COMMUNICATION.md),
 we'll be happy to help.
diff --git a/docs/MAPS.md b/docs/MAPS.md
index f9224bdbc4..e9c3de5df2 100644
--- a/docs/MAPS.md
+++ b/docs/MAPS.md
@@ -1 +1 @@
-This instruction is out of date. Please use [the new instructions](https://github.com/organicmaps/organicmaps/tree/master/tools/python/maps_generator).
+Please refer to maps_generator tool [instructions](../tools/python/maps_generator/README.md).
diff --git a/docs/STYLES.md b/docs/STYLES.md
new file mode 100644
index 0000000000..01647440c5
--- /dev/null
+++ b/docs/STYLES.md
@@ -0,0 +1,88 @@
+# Map styling and icons
+
+Here is the basic workflow to update styles:
+1. Edit the styles file you want, e.g. [`Roads.mapcss`](../data/styles/clear/include/Roads.mapcss)
+2. Run the `tools/unix/generate_drules.sh` script
+3. Test how your changes look in the app
+4. Commit your edits and files changed by the script
+5. Send a pull request!
+
+Please prepend `[styles]` to your commit message and add [Developers Certificate of Origin](CONTRIBUTING.md#legal-requirements) to it.
+Files changed by the script should be added as a separate `[styles] Regenerated` commit.
+
+Please check [a list of current styling issues](https://github.com/organicmaps/organicmaps/issues?q=is%3Aopen+is%3Aissue+label%3AStyles)
+and ["icons wanted" issues](https://github.com/organicmaps/organicmaps/issues?q=is%3Aopen+is%3Aissue+label%3AIcons+label%3A%22Good+first+issue%22).
+
+## Requirements
+
+To work with styles first [clone the OM repository](INSTALL.md#getting-sources).
+
+To run some scripts additional libraries are needed:
+```
+optipng
+protobuf 3.17.3 (3.18.0 doesn't work!)
+```
+
+## Files
+
+Map styles are defined in text files located in `data/styles/clear/include/`:
+* Forests, rivers, buildings, etc. [`Basemap.mapcss`](../data/styles/clear/include/Basemap.mapcss)
+* Their text labels [`Basemap_label.mapcss`](../data/styles/clear/include/Basemap_label.mapcss)
+* Roads, bridges, foot and bicycle paths, etc. [`Roads.mapcss`](../data/styles/clear/include/Roads.mapcss)
+* Their text labels [`Roads_label.mapcss`](../data/styles/clear/include/Roads_label.mapcss)
+* Icons for POIs and other features [`Icons.mapcss`](../data/styles/clear/include/Icons.mapcss)
+* City-specific subway networks [`Subways.mapcss`](../data/styles/clear/include/Subways.mapcss)
+* Light (default) theme colors: [`style-clear/colors.mapcss`](../data/styles/clear/style-clear/colors.mapcss)
+* Dark/night theme colors: [`style-night/colors.mapcss`](../data/styles/clear/style-night/colors.mapcss)
+
+There is a separate set of these style files for the navigation mode in `data/styles/vehicle/`.
+
+Icons are stored in [`data/styles/clear/style-clear/symbols/`](../data/styles/clear/style-clear/symbols/) and their dark/night counterparts are in [`data/styles/clear/style-night/symbols/`](../data/styles/clear/style-night/symbols/).
+
+## How to add a new icon
+
+1. Add an svg icon to `data/styles/clear/style-clear/symbols/` (and to `style-night` too)
+preferably look for icons in [collections OM uses already](../data/copyright.html#icons)
+2. Add icon rendering/visibility rules into `data/styles/clear/include/Icons.mapcss` and to "navigation style" `data/styles/vehicle/include/Icons.mapcss`
+3. Run `tools/unix/generate_symbols.sh` to add new icons into skin files
+4. Run `tools/unix/generate_drules.sh` to generate drawing rules for the new icons
+
+## How to add a new map feature / POI type
+
+1. Add it into `data/mapcss-mapping.csv` (or better replace existing `deprecated` line) to make OM import it from OSM
+2. If necessary merge similar tags in via `data/replaced_tags.txt`
+3. Add a new icon (see [above](#how-to-add-a-new-icon))
+4. If a new POI should be OSM-addable/editable then add it to `data/editor.config`
+5. Add new type translation into `data/strings/types_strings.txt`
+6. Add search keywords into `data/categories.txt`
+7. Run `tools/unix/generate_localizations.sh` to validate and distribute translations into iOS and Android
+8. Add new or fix current classifier tests at `/generator/generator_tests/osm_type_tests.cpp` if you can
+9. Ideally, test the changes locally by [generating](MAPS.md) some small region map
+10. Relax and wait for the next maps update :)
+
+Changing display zoom level for features (e.g. from z16- to z14-) might
+not take effect until map's geometry/scale index is rebuilt (or a whole map regenerated):
+1. [Build](INSTALL.md#building) the `generator_tool` binary
+2. Put a map file, e.g. `Georgia.mwm` into the `data/` folder in the repo
+3. Run
+```
+../omim-build-release/generator_tool --generate_index=true --output="Georgia"
+```
+4. The index of `Georgia.mwm` will be updated in place
+
+If e.g. `area` style rules are added for a feature that didn't have them before, then the rules
+won't take effect until map files are regenerated.
+
+## Technical details
+
+Map style files syntax is based on [MapCSS/0.2](https://wiki.openstreetmap.org/wiki/MapCSS/0.2),
+though the specification is not supported in full and there are OM-specific extensions to it.
+
+The `tools/unix/generate_drules.sh` script uses a customized version of [Kothic](https://github.com/kothic/kothic)
+stylesheet processor to compile MapCSS files into binary drawing rules files `data/drules_proto*.bin`.
+The processor also produces text versions of these files (`data/drules_proto*.txt`) to ease debugging.
+
+The `tools/unix/generate_symbols.sh` script assembles all icons into skin files in various resolutions (`data/resources-*/symbols.png` and `symbols.sdf`).
+
+There is a Designer version of the QT desktop app, which facilitates development
+by rebuilding styles and symbols quickly. Though building of the Designer tool is limited to macOS at the moment.
diff --git a/docs/TRANSLATIONS.md b/docs/TRANSLATIONS.md
new file mode 100644
index 0000000000..6d1ededb98
--- /dev/null
+++ b/docs/TRANSLATIONS.md
@@ -0,0 +1,75 @@
+# Translations
+
+Adding and updating translations is easy!
+1. Change the translation file you want, e.g. [strings.txt](../data/strings/strings.txt)
+2. Commit your changes
+3. Send a pull request!
+
+Please prepend `[strings]` to your commit message and add [Developers Certificate of Origin](CONTRIBUTING.md#legal-requirements) to it.
+
+Then run a `utils/unix/generate_localizations.sh` script and add the changes as a separate `[strings] Regenerated` commit.
+But if you can't run it - don't worry, its not mandatory!
+
+## Translation files
+
+- Application UI strings: [`data/strings/strings.txt`](../data/strings/strings.txt)
+
+- A few iOS specific strings: [`iphone/plist.txt`](../iphone/plist.txt)
+
+
+- Android stores description: [`android/src/google/play/listings/`](../android/src/google/play/listings/)
+
+- Apple AppStore description: [`iphone/metadata/`](../iphone/metadata/)
+
+
+- Names of map features/types: [`data/strings/types_strings.txt`](../data/strings/types_strings.txt)
+
+- Search keywords/aliases/synonyms for map features: [`data/categories.txt`](../data/categories.txt)
+
+- Search keywords for cuisine types: [`data/categories_cuisines.txt`](../data/categories_cuisines.txt)
+
+
+- Text-to-speech strings for navigation: [`data/strings/sound.txt`](../data/strings/sound.txt)
+
+
+- Popular brands of map features: [`data/strings/brands_strings.txt`](../data/strings/brands_strings.txt)
+
+- Search keywords for popular brands: [`data/categories_brands.txt`](../data/categories_brands.txt)
+
+
+Language codes used are from [ISO 639-1 standard](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).
+If a string is not translated into a particular language then it falls back to English or a "parent" language (e.g. `es-MX` falls back to `es`).
+
+## Tools
+
+To find strings without translations substitute `ar` with your language code and run the following script:
+```
+tools/python/strings_utils.py -l ar -pm
+```
+By default it searches `strings.txt`, to check `types_strings.txt` add a `-t` option.
+There are many more other options, e.g. print various translation statistics, validate and re-format translation files.
+Check `tools/python/strings_utils.py -h` to see all of them.
+
+In some cases automatically translated strings are better than no translation at all.
+There is a script to automate given string's translation into multiple languages.
+Please [install Translate Shell](https://www.soimort.org/translate-shell/#installation) first to be able to run it.
+
+```
+tools/unix/translate_categories.sh "Route"
+```
+
+## Technical details
+
+Most of the translation files (strings, types_strings...) are in Twine file format ([syntax reference](../tools/twine/README.md)).
+OM uses a custom version of the [Twine](https://github.com/organicmaps/twine)
+tool (resides in `tools/twine/` submodule) to generate platfrom-native (Android, iOS)
+localization files from a single translation file.
+
+The `utils/unix/generate_localizations.sh` script launches this conversion
+(and installs Twine beforehand if necessary).
+
+Search keywords translation files use a custom format described in the beginning of `data/categories.txt`.
+
+A `tools/python/clean_strings_txt.py` script is used to sync `strings.txt` with real UI strings usage as found in the codebase.
+
+There are preliminary plans to refactor translations workflow and migrate to Weblate.