[docs] various docs improvements

Signed-off-by: Harry Bond <[email protected]>

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,31 +1,36 @@
 ---
 name: Bug Report
-about: Describe your issue in details to help us improve Organic Maps
+about: Describe your issue in detail to help us improve Organic Maps
 title: ''
 labels: ''
 assignees: ''
 
 ---
 
 **Describe the issue**
-Please write here a clear and concise description of what the bug/issue is about.
+Please write a clear and concise description of the issue here.
+
 
 **Steps to reproduce**
 1. Go to '...'
 2. Click on '....'
 3. Scroll down to '....'
 4. See error
 
-**Expected behavior**
+
+**Expected behaviour**
 A clear and concise description of what you expected to happen.
 
+
 **Screenshots**
 If applicable, add screenshots or screen recordings to help explain your problem.
 
+
 **System information:**
  - Operating system and its version: [iOS 12, Android 10, Ubuntu 22, MacOS Big Sur, etc.]
- - Organic Maps version: [you can find it by tapping the button with the green OrganicMaps logo, bottom left of the main screen on Android, or the `?` button on iOS]
- - Device Model: [e.g. iPhone6, Samsung S22]
+ - Organic Maps version: [you can find it by tapping the button with the green Organic Maps logo, bottom left of the main screen on Android, or the `?` button on iOS]
+ - Device Model: [e.g. iPhone 6, Samsung S22]
+
 
 **Additional context**
-Please add any other context and important details/notes/comments about the problem here.
+Please add any other context or comments here that may be useful.

.github/ISSUE_TEMPLATE/config.yml

@@ -2,10 +2,10 @@ blank_issues_enabled: true
 contact_links:
   - name: Discussions
     url: https://github.com/organicmaps/organicmaps/discussions
-    about: Discuss the usage of OrganicMaps, ask questions, or talk about ideas that are not yet actionable.
+    about: Discuss the usage of Organic Maps, ask questions, or talk about ideas that aren't yet actionable.
   - name: Translations
     url: https://github.com/organicmaps/organicmaps/blob/master/docs/TRANSLATIONS.md
     about: Translate Organic Maps into your language
   - name: News
     url: https://organicmaps.app/news/
-    about: Check the latest project news
+    about: Check the latest project news

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,6 +1,6 @@
 ---
-name: Feature request
-about: Suggest an idea for OrganicMaps
+name: Feature Request
+about: Suggest an idea for Organic Maps
 title: ''
 labels: [Enhancement]
 assignees: ''
@@ -11,12 +11,15 @@ assignees: ''
 A clear and concise description of what the problem is. For example:
 I'm always frustrated when [...]
 
-**Describe the solution you would like**
+
+**Describe the ideal solution**
 A clear and concise description of what you want to see in Organic Maps.
 
+
 **Describe alternatives you have considered**
 - How do you solve this issue now with Organic Maps or other apps?
 - Attach any examples, screenshots, or screen recordings from other apps that help us to better understand the idea.
 
+
 **Additional context**
 Add any other context or screenshots about the feature request here.

README.md

@@ -2,8 +2,8 @@
 
 <a name="install"/>
 
-[Organic Maps](https://organicmaps.app) is a free Android & iOS offline maps app for travelers, tourists, drivers, hikers, and cyclists.
-It uses crowd-sourced [OpenStreetMap](https://www.openstreetmap.org) data and is developed with love by creators of **MapsWithMe** app (later renamed to **Maps.Me**) and by our community.
+[Organic Maps](https://organicmaps.app) is a free Android & iOS offline maps app for travellers, tourists, drivers, hikers, and cyclists.
+It uses crowd-sourced [OpenStreetMap](https://www.openstreetmap.org) data and is developed with love by the creators of **MapsWithMe** (later renamed to **Maps.Me**) and by our community.
 No ads, no tracking, no data collection, no crapware. Your [donations](https://organicmaps.app/donate/) and positive reviews motivate and inspire us, thanks ❤️!
 
 <p float="left">
@@ -36,14 +36,14 @@ No ads, no tracking, no data collection, no crapware. Your [donations](https://o
 
 ## Features
 
-Organic Maps is the ultimate companion app for travelers, tourists, hikers, and cyclists:
+Organic Maps is the ultimate companion app for travellers, tourists, hikers, and cyclists:
 
-- Detailed offline maps with places that don't exist on other maps, thanks to [OpenStreetMap](https://osm.org)
+- Detailed offline maps with places that don't exist on other maps, thanks to [OpenStreetMap](https://openstreetmap.org)
 - Cycling routes, hiking trails, and walking paths
 - Contour lines, elevation profiles, peaks, and slopes
 - Turn-by-turn walking, cycling, and car navigation with voice guidance
 - Fast offline search on the map
-- Bookmarks and tracks export and import in KML, KMZ, GPX formats
+- Bookmarks and tracks import and export in KML, KMZ & GPX formats
 - Dark Mode to protect your eyes
 - Countries and regions don't take a lot of space
 - Free and open-source
@@ -56,7 +56,7 @@ Organic Maps is pure and organic, made with love:
 - Saves your battery
 - No unexpected mobile data charges
 
-Organic Maps app is free from trackers and other bad stuff:
+Organic Maps is free from trackers and other bad stuff:
 
 - No ads
 - No tracking
@@ -69,7 +69,7 @@ Organic Maps app is free from trackers and other bad stuff:
 - No crapware
 - ~~No pesticides~~ Purely organic!
 
-The Android application is verified by <a href="https://reports.exodus-privacy.eu.org/en/reports/app.organicmaps/latest/">Exodus Privacy Project:
+The Android application is verified by the <a href="https://reports.exodus-privacy.eu.org/en/reports/app.organicmaps/latest/">Exodus Privacy Project:
 
 <img src="docs/privacy/exodus.png" width="400">
 </a>
@@ -92,20 +92,20 @@ At Organic Maps, we believe that privacy is a fundamental human right:
 
 - Organic Maps is an indie community-driven open-source project
 - We protect your privacy from Big Tech's prying eyes
-- Stay safe no matter wherever you are
+- Stay safe no matter where you are
 
 Reject surveillance - embrace your freedom.
 
 [**Give Organic Maps a try!**](#install)
 
-## Who is paying for the free app?
+## Who is paying for the development?
 
-The app is free for everyone. Please [donate](https://organicmaps.app/donate) to support us!
+The app is free for everyone, so we rely on donations. Please donate at [organicmaps.app/donate](https://organicmaps.app/donate) to support us!
 
 ### Our sponsors
 
 [Mythic Beasts](https://www.mythic-beasts.com/) ISP [provides us](https://www.mythic-beasts.com/blog/2021/10/06/improving-the-world-bit-by-expensive-bit/)
-two virtual servers with 400 TB/month of free bandwidth to help our users with
+two virtual servers with 400 TB/month of free bandwidth to host and serve
 maps downloads and updates.
 
 ## Copyrights
@@ -114,11 +114,11 @@ Licensed under the Apache License, Version 2.0. See
 [LICENSE](https://github.com/organicmaps/organicmaps/blob/master/LICENSE),
 [NOTICE](https://github.com/organicmaps/organicmaps/blob/master/NOTICE)
 and [data/copyright.html](http://htmlpreview.github.io/?https://github.com/organicmaps/organicmaps/blob/master/data/copyright.html)
-files for more information.
+for more information.
 
 ## Governance
 
-See [GOVERNANCE](docs/GOVERNANCE.md).
+See [docs/GOVERNANCE.md)](docs/GOVERNANCE.md).
 
 ## Contributing
 
@@ -134,7 +134,7 @@ Please join our beta program, suggest your features, and report bugs:
 
 ## Feedback
 
-- **Rate us on [App Store](https://apps.apple.com/app/organic-maps/id1567437057)
+- **Rate us on the [App Store](https://apps.apple.com/app/organic-maps/id1567437057)
 and [Google Play](https://play.google.com/store/apps/details?id=app.organicmaps)**.
 - **Star us on GitHub**.
 - Report bugs or issues to [the issue tracker](https://github.com/organicmaps/organicmaps/issues).

docs/COMMIT_MESSAGES.md

@@ -24,7 +24,7 @@ Any commit needs a helpful message. Mind the following guidelines when committin
 
 4. Start a sentence with a capital letter.
 5. Do not end the subject line with a period.
-6. Do not put "gh-xx", "closes #xxx" to the subject line.
+6. Do not put "gh-xx", "closes #xxx" in the subject line.
 7. Use the imperative mood in the subject line.
 
    - A properly formed Git commit subject line should always be able to complete

docs/CONTRIBUTING.md

@@ -19,7 +19,7 @@ list of actions leading to a bug, a log file produced by the app.
 
 When using Organic Maps 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 [email protected]. Enabling logs in Organic Maps settings on Android
+faster if you send it to <[email protected]>. Enabling logs in Organic Maps settings on Android
 before sending the bug report also helps us a lot with debugging.
 
 ### Feature Requests
@@ -34,7 +34,7 @@ See [translations instructions](TRANSLATIONS.md) for details.
 ### Map styling and icons
 
 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.
+There is always something to improve, adding new map features, fine tuning the colour palette etc.
 And every time we add a new map feature/POI we need a good and free-to-use icon.
 
 See [styles and icons instructions](STYLES.md) for details.

docs/DCO.md

@@ -4,7 +4,7 @@
 
 This project uses **Developer's Certificate of Origin (DCO)** instead of **Contributor License Agreement (CLA)**. It is often easier to get started contributing under a DCO than a CLA.
 
-When one is developing software for a company they need to have the company sign the Corporate CLA prior to submitting contributions. That means there is a step after the business decides to contribute where legal documents need to be signed and exchanged. Once this is done there are steps to associate people with those legal documents. All of this takes time. In some companies this process can take weeks or longer.
+When one is developing software for a company they need to have the company sign the Corporate CLA before contributing. That means there is a step after the business decides to contribute where legal documents need to be signed and exchanged. Once this is done there are steps to associate people with those legal documents. All of this takes time. In some companies this process can take weeks or longer.
 
 We wanted to make it simpler to contribute.
 

docs/PR_GUIDE.md

@@ -1,11 +1,11 @@
 # Pull Request Guide
 
-## Writing good PR:
+## Writing a good Pull Request (PR):
 
-- PR should be small and reflect only one idea, a feature, a bugfix, or a refactoring. In most cases, a PR of 100 lines or less is considered as a PR of normal size and a PR of 1000 lines as big one
+- A PR should be small and reflect only one idea, a feature, a bugfix, or a refactoring. In most cases, a PR of 100 lines or less is considered as a PR of normal size and a PR of 1000 lines as big one
 - If a PR implements two different features, refactoring, or bugfixes, it should be split into several PRs
 - The description field of every PR should contain a description, links to a ticket or/and links to the confluence
-- If a PR implements a complex math task, the description should contain a link to the proof of the solution or a link to a trusted source
+- If a PR implements a complex algorithm, the description should contain a link to the proof of the solution or a link to a trusted source
 - All PRs should contain links to the corresponding tickets. The exception is refactoring if there's nothing to test after it. The reason for that is that every feature or bugfix should be tested by testers after it's implemented
 - Every commit of all PRs should be compilable under all platforms. All tests should pass. So if changing of code breaks unit or integration tests these tests should be fixed in the same commit
 - Every commit should reflect a completed idea and have an understandable comment. Review fixes should be merged into one commit
@@ -32,7 +32,7 @@
 - A reviewer should pay attention not only to the code base but also to the description of the PR and commits
 - A PR may be merged by a reviewer if all the following items are fulfilled: (1) the PR isn't marked as a draft; (2) all reviewers which have started to review the PR, approved it; (3) all reviewers which are added as reviewers of the PR, have approved it
 - If a reviewer doesn't have time to review all the PR they should write about it explicitly. For example, LGTM for android part
-- If a reviewer and a developer cannot find a compromise, the third opinion about it should be asked
+- If a reviewer and a developer cannot find a compromise, a third opinion should be sought
 - All comments about blank lines should be considered as optional
 
 ## Recommendations:
@@ -42,5 +42,5 @@
 - If you are solving a big task it's worth splitting it into subtasks and develop one or several PRs for every subtask.
 - If it's necessary to make a big change list which should be merged to master at once, it's worth creating a branch and make PRs on it. Then to make PR with all commits of the branch to the master
 - In most cases refactoring should be done in a separate PR
-- If you want to make a refactoring which touches a significant part of the code base, it's worth discussing it with all developers before starting changing code
-- It's worth using Resolve conversation button to minimize the list of comments of a PR
+- If you want to refactor a significant part of the code base, it's worth discussing it with all developers before starting work
+- It's worth using the 'Resolve' conversation button to minimize the list of comments in a PR

docs/RELEASE_MANAGEMENT.md

@@ -1,12 +1,12 @@
 # Release Management
 
-## Apple AppStore
+## Apple App Store
 
-### Upload metadata and screenshots to AppStore
+### Upload metadata and screenshots to the App Store
 
 Use [GitHub Actions](../.github/workflows/ios-release.yaml).
 
-### Checking metadata
+### Check metadata
 
 Use [GitHub Actions](../.github/workflows/ios-check.yaml).
 
@@ -16,9 +16,9 @@ Local check:
 ./tools/python/check_store_metadata.py ios
 ```
 
-### Downloading screenshots from AppStore
+### Downloading screenshots from the App Store
 
-Get xcode/keys/appstore.json - AppStore API Key.
+Get xcode/keys/appstore.json - App Store API Key.
 
 Get screenshots/ - a repository with screenshots.
 

docs/STRUCTURE.md

@@ -19,7 +19,7 @@
 
 - `countries.txt` - map files hierarchy and checksums.
 - `countries_meta.txt` - country/region languages and driving sides.
-- `hierarchy.txt` - countries / map regions hierarchy, languages used and Wikidata IDs.
+- `hierarchy.txt` - countries/map regions hierarchy, languages used and Wikidata IDs.
 
 - `faq.html` - FAQ text displayed in the "?"/Help screen.
 - `copyright.html` - attributions to 3rd-party libraries, map data, icons, fonts.
@@ -32,11 +32,11 @@ There are some other files not mentioned here.
 ### Map features / classificator
 
 - `mapcss-mapping.csv` - mapping between OSM tags and OM types.
-- `replaced_tags.txt` - similar OSM tags merged.
+- `replaced_tags.txt` - merging similar OSM tags.
 - `mixed_tags.txt` - pedestrian streets of high popularity.
 
 - `editor.config` - built-in OSM data editor configuration (editable POIs, their attributes, etc.).
-- `config.xsd` - xml schema for `editor.config`.
+- `config.xsd` - XML schema for `editor.config`.
 
 Automatically generated:
 - `classificator.txt` - hierarchical list of all OM types.
@@ -46,7 +46,7 @@ Automatically generated:
 
 - `resources-default/` -
 - `resources-svg/` - social networks icons
-- `search-icons/svg/` - source svg files for search categories icons
+- `search-icons/svg/` - source SVG files for search categories icons
 - `styles/` - map [style files](STYLES.md#files)
 
 Automatically [generated](STYLES.md#technical-details):
@@ -61,7 +61,7 @@ Automatically [generated](STYLES.md#technical-details):
 - `categories.txt`,`categories_cuisines.txt`,`categories_brands.txt`,`countries_names.txt`
 
 Misc strings:
-- `mwm_names_en.txt` - english names for map regions.
+- `mwm_names_en.txt` - English names for map regions.
 - `countries_synonyms.csv` - alternative country names.
 - `synonyms.txt` - country and region names abbreviations and short names.
 - `languages.txt` - native language names.
@@ -76,8 +76,8 @@ Automatically [generated](TRANSLATIONS.md#technical-details):
 - `generator/` - map building tool.
 - `poly_borders/` - borders post-processing tool.
 - `skin_generator/` - a console app for building skin files with icons and symbols.
-- `topography_generator/` - isolines from SRTM data.
-- `track_generator/` - generate smooth tracks based on waypoints from KML.
+- `topography_generator/` - generates isolines from SRTM data.
+- `track_generator/` - generates smooth tracks based on waypoints from KML.
 
 ## C++ Core
 
@@ -116,4 +116,4 @@ Automatically [generated](TRANSLATIONS.md#technical-details):
 
 ## Documentation
 
-The main docs are in the `docs/` directory, however some tools have their own readmes, etc.
+The main docs are in the `docs/` directory, however some tools have their own READMEs, etc.

docs/STYLES.md

@@ -90,7 +90,7 @@ a `styles/` subfolder of maps directory on the device
 Changing display zoom level for features (e.g. from z16- to z14-) might
 not take effect until map's visibility/scale index is rebuilt:
 1. [Build](INSTALL.md#desktop-app) the `generator_tool` binary
-2. Put a map file, e.g. `Georgia.mwm` into the `data/` folder in the repo
+2. Put a map file, e.g. `Georgia.mwm` into the `data/` folder in the repository
 3. Run
 ```
 ../omim-build-release/generator_tool --generate_index=true --output="Georgia"

docs/SUBWAY_GENERATION.md

@@ -1,11 +1,11 @@
 # Subway layer generation
 
-For the subway layer to be available in Organic Maps a `SUBWAY_URL`
+For the subway layer to be available in Organic Maps, a `SUBWAY_URL`
 parameter ought to be provided to the
 [map generator](https://github.com/organicmaps/organicmaps/tree/master/tools/python/maps_generator).
-Normally you can specify the link https://cdn.organicmaps.app/subway.json
-to a regularily updatable file.
-This instruction describes how to manually build subway layer file.
+Normally you can specify this link https://cdn.organicmaps.app/subway.json,
+which provides a regularly updated file.
+These instructions describe how to manually build a subway layer file.
 
 Japan is used as target country but any other region from one city to the
 whole planet is also applicable.
@@ -21,15 +21,15 @@ whole planet is also applicable.
     If you already have some not too outdated \*.o5m version, it is enough
     because the subway generation script will update it with `osmupdate`.
 
-1.  With [Organic Maps subways](https://github.com/organicmaps/subways) repository deployed,
+1.  With the [Organic Maps subways](https://github.com/organicmaps/subways) repository deployed,
     run `scripts/process_subways.sh` bash script or prepare your own script
     which launches `process_subways.py` and `validation_to_html.py` scripts
     with suitable options.
 
-1.  Analyze HTML output obtained at the previous step. Broken transport
+1.  Analyse the HTML output obtained at the previous step. Broken transport
     networks won't be included into the map.
 
-1.  Run `tools/python/transit/transit_graph_generator.py` from `omim`.
+1.  Run `tools/python/transit/transit_graph_generator.py` from the repository root.
 
 The last three steps may be expressed as the following shell script: