Add new features to Readme

README.md

@@ -1,27 +1,36 @@
 # wmch-interactive-maps
-A configurable backend to generate interactive maps on top of Wikidata.
 
-## Settings
+A configurable backend to generate and show interactive maps on top of Wikidata.
 
-A base configuration file is available on `config.js`.
+## User manual
 
-Local settings like database name and authentication data are available in the git ignored `localconfig.json` in the following formats.
+User manual in multiple languages is loaded on [i18n_man/index](https://github.com/synapta/wmch-interactive-maps/tree/master/i18n_man/index)
+
+The user manual is available inside the app along the screenshots at the `/wizard/man/index` path.
 
-TL;DR: Copy localconfig.example.json to localconfig.json
+## Installation
 
-Create directories:
+Create `screenshots` and `local` directories:
 
 `mkdir -p screenshots && mkdir -p local`
 
-### url
+Screenshots directory will contains preview files for maps, local directory could contain the sqlite database and other development data.
+
+### Add localconfig.json
 
-On localconfig.json, set the url to the production url. It will be used to:
-- Get preview
-- Expose the path to the user
+***TL;DR: Copy localconfig.example.json to localconfig.json. Change data as needed.***
+
+Local settings like database name and authentication data are available in the git ignored `localconfig.json` in the following formats.
 
-It will be something like https://interactivemap.wikimedia.swiss/.
+On localconfig.json, set the url to the production url. It will be used to expose the path to the user, something like https://example.org/.
 
-### Database
+### config.js
+
+A global base configuration file is available on `config.js`.
+
+It contains available map styles based on sources listed on [Tile servers](https://wiki.openstreetmap.org/wiki/Tile_servers) page on OpenStreetMap.
+
+### Set up database
 
 Data can be saved by two different connectors, SQLite and MariaDB.
 
@@ -65,7 +74,7 @@ Port and dialectOptions can be omitted, getting the default values above.
 
 [Reference for MariaDB](http://docs.sequelizejs.com/manual/usage.html#mariadb)
 
-## Run the app
+## Run
 
 `node app.js`
 
@@ -76,9 +85,27 @@ Port and dialectOptions can be omitted, getting the default values above.
 15 Mar 10:46:31 - WMCH Interactive maps listening at http://:::9089
 
 
-### Urls
-- Backend: http://localhost:9089/wizard/
-- Frontend: http://localhost:9089/
+### Run the screenshot server
+
+The screenshot server is used to take a screenshot of the map just before a map is saved to the database.
+
+Port and url are specified on config.json.
+
+`node screenshot.js`
+
+Both the app.js and screenshot.js must be running at the same time.
+
+### Auto-update and keep running
+
+To auto-update and keep running the node servers in development environment on changes, you can use:
+
+`nodemon MYSERVERSCRIPT.js --port MYPORT`
+
+In this case nodemon must be installed globally.
+
+## Languages
+
+The app supports multiple languages.
 
 ### Language negotiation
 
@@ -89,29 +116,71 @@ To force a particular language in the format using the url use the `l` parameter
 - http://localhost:9089/wizard/?l=it
 - http://localhost:9089/wizard/?l=it-CH
 
+A dropdown to change language is provided on both backend and frontend.
+
 ### Translations
 
 All translations are key-based and hosted in JSON file named after the [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) code under the i18n folder.
 
-Directory structure is.
+Directory structure is associated with the respective section.
 
 ~~~
 i18n
-├── wizard
-│    ├── en.json
-│    └── it.json
-└── frontend
-    ├── en.json
-    └── it.json
+|-- admin
+|   |-- en.json
+|   `-- it.json
+|-- frontend
+|   |-- en.json
+|   `-- it.json
+|-- manual
+|   |-- en.json
+|   `-- it.json
+`-- wizard
+    |-- en.json
+    `-- it.json
+
 ~~~
 
-The reference is the **en.json** file.
+To add a new translation:
+
+1. Add a new ISO 639-1 file to each directory inside `i18n` copying a file like `en.json` and changing the keys.
+2. Edit `config.json` and add a new language code, e.g. `{"code": "ja", "name": "日本語"}`
+
+## Paths
+
+On development or locally, the main paths are:
+
+- Backend: http://localhost:9089/admin/
+- Wizard (backend and user manual): http://localhost:9089/wizard/
+- Frontend: http://localhost:9089/
+
+If the edit must be limited, `/admin` and `/wizard` paths can be protected via webserver.
+
+## External resources
+
+External libraries are loaded via Wikimedia CDN where availables:
+
+- [https://tools.wmflabs.org/cdnjs/](https://tools.wmflabs.org/cdnjs/)
+
+External fonts are loaded via:
+
+- [https://tools.wmflabs.org/fontcdn/](https://tools.wmflabs.org/fontcdn/)
+
+## Special commands
 
-### Map styles
+### Maintenance scripts
 
-Map styles is based on sources listed on [Tile servers](https://wiki.openstreetmap.org/wiki/Tile_servers).
+If a relevant change to the code will affect all maps in the database, screenshots can be regenerated.
 
-### Icon list
+To regenerate all preview screenshots:
+
+`node maintenance.js -P`
+
+Help for all available commands:
+
+`node maintenance.js --help`
+
+### Generate a new icon list
 
 Icon list can be selected between [those available on Semantic UI](https://semantic-ui.com/elements/icon.html) and saved on /public/js/icons.json.
 
@@ -135,35 +204,7 @@ JSON.stringify(myels, null, ' ');
 
 Then expand and copy object to get a JSON array.
 
-### External libraries
-
-External libraries are loaded via Wikimedia CDN where availables:
-- https://tools.wmflabs.org/cdnjs/
-
-## Run the screenshot server
+Semantic UI Icons are available on wizard searching by class name.
 
-The screenshot server is used to take a screenshot of the map just before a map is saved to the database.
+These steps are useful when the Semantic UI version is changed.
 
-Port and url are specified on config.json.
-
-`node screenshot.js`
-
-## Auto-update and keep running
-
-To auto-update and keep running the node servers in development environment, you can use:
-
-`nodemon MYSERVERSCRIPT.js --port MYPORT`
-
-## Sticky maps
-
-Maps can be set as sticky altering the sticky column. Greater sticky value will put the item on the top of the map list. Default value for sticky column is 0.
-
-## Maintenance scripts
-
-Regenerate all preview screenshots:
-
-`node maintenance.js -P`
-
-Help for all available commands:
-
-`node maintenance.js --help`