Add F.A.Q. section

[strump]

Fixes #6

I picked PR #171 "[WIP] Added text to speech instructions" and added F.A.Q. questions from @biodranik coffers. Implemented using Zola taxonomies.

Almost all screenshots are made on Android.

Blank spaces are present.

What to do with *.po files? Should I add texts from new pages to PO file?

Update 2023-10-09

Create subfolder for each FAQ question.

Using title propety instead of custom extra.question.

Added ordering by extra.order field. weight is not available for taxonomy terms.

[cloudflare-pages[bot]]

Deploying with    Cloudflare Pages

Latest commit:	82f2189
Status:	✅  Deploy successful!
Preview URL:	https://2877c827.organicmaps.pages.dev
Branch Preview URL:	https://faq-plus-tts.organicmaps.pages.dev

View logs

[strump]

@Jean-BaptisteC thanks for feedback. I changed Android version question and fixed links to OSM.

Whant do you mean by "subtitle has been remove"? Do you have screenshot of road avoidance settings?

[Jean-BaptisteC]

Subtitle IHM has been removed here https://github.com/organicmaps/organicmaps/pull/6251

[rtsisyk]

I am not sure that the current structure would be straightforward to the user. For example, if I have an issue with routing in the Android app, it is "Android question" or "Routing question"?

[rtsisyk]

My recommendation is to land the structure (at least two section with 1-2 sample questions in each) and discuss the content itself separately. Otherwise it will never end.

[strump]

@rtsisyk with current structure we can put same question to different sections:

taxonomies:
  faq: ["Android", "Routing"]  # any number of sections you'd like

The question is going to be copied to all sections.

I agree that we should finish with structure and move to content.

[oleg-rswll]

Sharing the new design for the website which is in progress. The Support page will have a search of all the FAQ questions and each one can be tagged with category and OS (multiple categories and multiple OS). https://www.figma.com/file/oNEntnxkOIA0DrsTL1dRpD/Organic-Maps?type=design&node-id=0-1&mode=design&t=f9deMAqnVhny3buD-0

The progress of the site: https://preprod.organicmaps.pages.dev/

FAQ document with the latest updates. It still needs work, but includes questions/answers from all the sources available. https://docs.google.com/document/d/10i_7mv7w5LqO6QZLsqIT9pyIPNiXCVasyLkmsJ1LWsA/edit#heading=h.qrbphg2zgpo9

[gpesquero]

Sharing the new design for the website which is in progress.

Wow!! This brand new website looks quite promising!!!

What is your plan regarding the FAQs? Cause I'm currently dealing with the FAQs in the "zola" version of the website and I also see that you have a link to a Google Doc with a merge of different FAQs.

Please let me know that is the roadmap that you have regarding the FAQs, in order to optimize the work... Do you plan to move the FAQs in the Google Doc to the zola version? or will they go directly to the new website?

[biodranik]

Note that google docs FAQ needs to be reviewed first.

[biodranik]

The new website should work on Zola, so the FAQ section implementation from this PR should be helpful. CC borntojesus

[oleg-rswll]

@gpesquero The new website design will use the same underpinnings as the current website (Zola, Weblate), so your work with Zola aligns with the new website. Adding the new FAQ content will be independent of the website update, if the content is ready early, it can be added before the new website is launched.

The Google Doc still needs updating to clarify the question and answers. If you're interested in helping with that, I can give you access.

[gpesquero]

If you're interested in helping with that, I can give you access.

Sure, I can help updating these FAQs... I've already done some changes in the file with my Google account, which appear now as "suggestions"...

[oleg-rswll]

@gpesquero great, please request edit access in the Google Doc.

[gpesquero]

@gpesquero great, please request edit access in the Google Doc.

Sorry @oleg-pah, but I cannot find the way to request the edit access in Google Docs...

The only available modes are Suggesting or Viewing, but the Editing option is greyed...

... and there's is no "Request Edition" button anyware in the Google Docs interface or menu.

Can you please check if you can modify the Share options of this file to include my Google user?

[oleg-rswll]

@gpesquero I see that you requested edit access, you now have access.

[rtsisyk]

What is preventing us from merging this PR? I need a structure to add more instructions.

[biodranik]

The FAQ structure should be finished properly. It is described here, and other requirements are here.

[strump]

Changed structure little bit. Now we have 3 levels:

• /faq/ - list of subjects
• /faq/android - list of questions for a subject
• /faq/bookmarks-02-remove/ - single question with answer

Some questions has one line answer. But we show it on a separate page. E.g. /faq/android-05-webview/. Is it ok?

[biodranik]

Thanks! Separate pages are needed for SEO and sharing anyway, so I don't see a big issue here. And we always can generate combined index pages from separate answers.

The path of each answer should have only the question's text in it, like /faq/how-to-remove-a-bookmark, ideally localized to different languages.

[strump]

Added explicit slug property to each FAQ page. Currently slug is a copy of title to get URLs:

• /faq/how-to-measure-distances-with-organic-maps-is-there-a-ruler/
• /faq/pochemu-marshruty-v-om-chestnye-i-otlichaiutsia-ot-drugikh-prilozhenii/

I had to change Zola config slugify.path from "safe" to "on".

[biodranik]

Thanks for the spirit to work on it!

1. Why slug is needed for the base English version? Renaming android-01-version to what-android-version-can-run-organic-maps (and removing its index.md slug) works just fine. Slug later can optionally be used for localized content for better SEO.
2. Why is custom extra: order: 10 variable is needed? Doesn't weight work as expected?
3. Is there a way to iterate over all subsections and display each Taxonomy (category) + its questions on the one /faq/ index page? Current taxonomies /faq/android/ can stay as is, they are also convenient.

[gpesquero]

I've already reviewed and updated the FAQ Google Docs document. I've left some comments in the doc with questions and doubts for some of the FAQ. Please review the document and provide feedback or answers to the questions raised...

My plan now is to move all the FAQs in this Google document into the FAQs in the faq_plus_tts branch. I will mark with a special paragraph color all the FAQs being or already moved to the git branch.

[biodranik]

Thanks for a lot of work! The first step should be to finish/finalize the FAQ structure. Only after that, we can start creating content files in the right way (with a proper path/name/header). @strump can you please help?

As you have already reviewed FAQ items, can you please help and incorporate the missing questions/answers from my user support notes? Many of them may already be incorporated.

They are not sorted, contain some duplicates, and may have non-questions items that should be rephrased. It also would be great to categorize FAQ items into different groups/tags, including ios/android.

1. Why Organic Maps is better than other maps?
2. What is the roadmap?
3. The history of the project
4. Who is involved in the project?
5. What versions of iOS and Android are supported? iOS 12+, Android 5+
6. How to move bookmarks and tracks from one list to another, ios and android difference
7. Compare our privacy policy with other maps apps. Tell your friends about the difference. https://organicmaps.app/privacy/
8. Why my position is not detected? (go outside, remove magnets/metal from the case, allow internet access for faster GPS fix, wait for several minutes, use GPS Test app…)
9. Why my position is incorrect? You may be anywhere in a blue circle. Position is rough by wifi, cellular network or ip address.
10. How to import bookmarks?
11. How to import all maps.me bookmarks?
12. How can I know what is that line or area on the map? Long tap it!
13. How can I bookmark an empty space? Long tap it.
14. How can I bookmark a specific coordinate? Type it in the search first.
15. When edits are uploaded to OSM?
16. Something is wrong/missing on the map! What should I do?
17. How are my map edits moderated?
18. How to add a building or a road, or some other type that is not in OM Editor yet? — Use other apps/osm.org
19. How do I see the map legend? - Press long tap or single tap.
20. How to build a route?
21. Can I see the elevation profile? Yes, in walking and cycling route preview.
22. How to measure a distance/where is the ruler tool?
23. How to add intermediate stops for a route?
24. If the edit location button is unavailable (in OSM) - then you need to update the maps (and the app) (we need to fix it… https://github.com/organicmaps/organicmaps/issues/6936 )
25. How to import GPX/KML/KMZ on iOS and Android? (same answer may be appropriate for different questions)
26. What are the gestures?
27. How to zoom with one hand? Tap, then tap again, and keep your finger up or down.
28. If there are lags in ui and random crashes, then most likely the data is stored on the SD card, and it is faulty (android only)
29. If TTS does not work, try the instructions [link] and restart OM
30. How to hide/show the interface buttons? Tap in the empty space hides the interface
31. Everything is running slow? Android and store cards on SD? SD cards are always slower than in internal memory. Buy a fast card, or store cards in internal memory, and enjoy it
32. Where to customize TTS speed volume, and where to customize on ios TTS (try to select text and play it, Speak in popup menu) https://support.apple.com/guide/iphone/spoken-content-iph96b214f0/ios
33. Sign up in github or telegram for news about the features you want (should add mailing list to the site too)
34. You can select the blue arrow of your position to see your current speed and altitude (add satellites there, error radius if wifi/cellular)
35. Add intermediate points for detour/bypass (how?)
36. You can enter anything in the search, not just what's in the categories, but any other type on the map displayed in the Place Page
37. Difference between fdroid and gp and web versions (there is no Google Play Services, which you can optionally disable, and which speeds up searching for a position via google using wifi and cellular)
38. TTS customization where and how? (finalize the page, there is a draft)
39. Crooked roadtrips/routes if you don't update maps or not all maps, we are constantly improving them. Update more often! Also check the same route at osm.org
40. How to send us a bug report? (ios + android)
41. How to enable logs (android only)?
42. What is the blue circle around the position - anywhere inside, talk about GPS accuracy, about not catching satellites indoors or near metal objects/sources of radiation or not catching them well
43. How to open/import KML and GPX in iOS
44. Importing tags into iOS on Cold Start from Files fails. Re-importing with OM running works. https://github.com/organicmaps/organicmaps/issues/4800
45. Why routes in OM are “honest” and different from other apps. OM builds the fastest route, checks every road on the way.
46. How to make sure that the map data and the version of the app are up to date?
47. How to recalibrate compass https://www.youtube.com/watch?v=-Uq7AmSAjt8
48. What to do if map download does not work.
49. Explain that bookmarks and tracks are saved locally and are not shared with anyone, not stored on servers and are private. And need manual backup for now.
50. If the position arrow is spinning frantically - the cause may be a magnet on the case, metal or radiation nearby, remove the source of the problem and calibrate with a special gesture https://www.youtube.com/watch?v=-Uq7AmSAjt8.
51. If the position on the iPhone is poorly determined - the cause may be a metal or a magnet on the case.
52. Why do I need to update the app often? We are constantly fixing a lot of bugs, map updates are still tied to app updates. We'll untie it.
53. There are gestures - Press the zoom buttons and drag up or down, or dab tap the map to zoom.
54. How do I delete tags or tracks?
55. What do the different icons on the position button (under the zoom buttons) mean? What are the map rotation modes? How to fix map north up?
56. Routing options are visible only when route can be modified by them. Otherwise they're hidden.
57. Secret commands in search: ?vulkan, ?gl, ?edits
58. Crooked direction arrow, points the wrong way - tell how to calibrate compass https://www.youtube.com/watch?v=-Uq7AmSAjt8.
59. How edits are uploaded on OpenStreetMap.org, how conflicts are resolved?
60. Uninstalling the app deletes ALL tags and tracks! Cloud backup is in the plans, one button backup of all lists is also in the plans
61. fix tts faq link to mapsme - make link in settings to our page with all tts https://4pda.to/forum/index.php?showtopic=200728&st=0#entry95121276 https://docs.google.com/spreadsheets/d/1kZ6cKY_BcCkxmGtCioQi9Z0SvhcWBkf427DQCWSwIDs/edit#gid=0 https://github.com/organicmaps/organicmaps.github.io/pull/32
62. TTS may not work because of some checkbox "allow TTS in background" on Android 11 Open your device's Settings app . Tap Accessibility, then tap Select to Speak. Tap Settings. At the top, turn on Read in background.
63. How to enable north from above?
64. Clicking on the small blue direction arrow in PP shows the direction dialog to the selected object.
65. What does a circle instead of a position arrow mean? (no compass sensor)
66. How do I delete imported tracks?
67. Update maps to the latest version to edit
68. Tablets do not have a compass sensor (you can see it on gsmarena), so it draws a circle and not an arrow
69. Google TTS is too fast https://github.com/organicmaps/organicmaps/issues/1080
70. How to edit and move tags and tracks in lists
71. CarPlay is always dark: check your CarPlay settings (NOT Organic Maps settings) when the device is connected, and select "auto" instead of "always dark": https://www.youtube.com/watch?v=ty6Ko7uBvNk.
72. How to search by coordinates - type them into the search.
73. How to disable Power Saving for Organic Maps on android (add to exceptions) so that downloads are not interrupted and maps launch faster (OM does not consume battery in the background, on the contrary, more battery is consumed if the application is killed by the system and constantly starts from scratch). https://www.popsci.com/diy/turn-off-battery-saver/
74. Android precise permission wasn't enabled => only approximate location is seen
75. OM builds wrong/bad route. Tell about osm, to check route there first, and then report to us if it's correct there.
76. iOS: how to share a crash with developers https://help.apple.com/xcode/mac/current/#/deve2819c518
77. Why isn't the feature XXX done yet?

[strump]

Changed structure. Now we have 2 levels:

/faq/ (link) - list of subjects and question titles /faq/bookmarks/how-to-add-intermediate-route-points/ - single question with answer

Refactoring of /contect/faq folders structure.

@biodranik we can't get rid of extra.order: %d property because Zola doesn't support "weight" property for taxonomy pages. See comment in Zola github: https://github.com/getzola/zola/issues/246#issuecomment-408480599

Sorting in taxonomies is another can of worm that I hope to defer for as long as possible

[oleg-rswll]

please help and incorporate the missing questions/answers from my user support notes? Many of them may already be incorporated.

@biodranik @strump including the latest questions in this document.

https://docs.google.com/document/d/10i_7mv7w5LqO6QZLsqIT9pyIPNiXCVasyLkmsJ1LWsA/edit

[biodranik]

Cool, looks great to me, many thanks @strump !

It would be great to make taxonomy/tags clickable in the /faq/ headers, and also list all tags at the top or at the bottom of each /faq/tag/ and /faq/tag/question/ pages.

[oleg-rswll]

• Folders need to be added, updated and removed to reflect the categories defined here: https://docs.google.com/document/d/10i_7mv7w5LqO6QZLsqIT9pyIPNiXCVasyLkmsJ1LWsA/edit
• The question/answer page should display the tags, for example the OS tag
• On the main FAQ page which lists the questions, Search is needed. Today there are 100+ questions and that is already a lot to read through to find the necessary one. As time goes on the list will grow even more.

[strump]

@biodranik

1. On /faq/ page category names are links now (everything is blue).

2. Added second-level menu to FAQ category and FAQ question pages:

F.A.Q. • Android • Bookmarks • General • iOS • Map • Routing • TTS

But I don't know how to mark question category. E.g. on the page https://99f9f351.organicmaps.pages.dev/faq/android/what-android-version-can-run-organic-maps/ how to tell that the question relates to Android? What if page has two or three categories?

[gpesquero]

Hi there!!

I've already reviewed and completed the FAQs in the Google Docs file and I've also traced that all missing questions/answers from the 77 user support notes listed here are somehow included in the FAQs. This traceability can be found at the end of the Google Docs File.

I understand that the next step would be to start to include all the FAQs from the Google Docs file into the faq_plus_tts branch, but first we also have to confirm which categories shall be used for the FAQs...

In the repository we currently have the following 7 "questions" categories:

1. Android
2. Bookmarks
3. General
4. iOS
5. Map
6. Routing
7. TTS

And these are the 12 "categories" included in the Doc file:

1. About OM
2. App
3. Operating the Map
4. Search
5. Route Planning & Routing
6. Favorites: Places & Tracks
7. Map Data
8. GPS & Compass
9. Features
10. Text-To-Speech (TTS)
11. Troubleshooting
12. Community Collaboration

Please confirm that these 12 categories are the ones to use...

[biodranik]

@strump thanks! The structure is almost ideal now. I've tested it and suggest removing folders for categories and keeping all articles in the root faq folder. Then each article can easily have more than one (localized!) taxonomy category without a hard-coded path.

But I don't know how to mark question category.

I suggest introducing a templates/faq/page.hmtl template and explicitly mentioning it in each md file as template: templates/faq/page.hmtl for easier customization.

Then you can access any page's taxonomy by checking page.taxonomies field.

@gpesquero before moving the content, let's polish this branch for the releasable state, by focusing on only a few articles first, translated into a few languages initially (as an example), so it can be merged. All other content can then be added later separately.

After a proposed fix, it would be very easy to edit/change the category of any article (or put it into several categories, or mark articles related only to iOS or to Android) at any time.

[strump]

@biodranik when I wrote "But I don't know how to mark question category." I mean that I don't know how to visualize categories in top menu:

Make "Android" bold, different color, or with some icon?

[gpesquero]

@gpesquero before moving the content, let's polish this branch for the releasable state, by focusing on only a few articles first, translated into a few languages initially (as an example), so it can be merged. All other content can then be added later separately.

I've launched PR 204 with just a couple of FAQs as example for testing & validation. Please have a look at this PR, as it needs some fixing...

[biodranik]

@strump it's not critical ATM, make it bold for example. We'll prettify it later, finishing with the structure is more important.

Let's add some ru translations to test if taxonomy works, to also help @gpesquero

[strump]

@biodranik there's a problem with multilanguage and toxonomy in one project. See issue. Getting error faq\android-01-version\index.uk.md' has taxonomy 'faq' which is not defined in config.toml.

I'll try workaround from that issue discussions.

[biodranik]

@strump the same (or similar?) issue was mentioned by @borntojesus on the preprod branch.

The linked zola issue should be already resolved. It looks like taxonomies should be defined for each language separately (and maybe also duplicated in the root too).

What is the best way to reproduce the issue here?

[biodranik]

@strump let's polish this branch and prepare it to merge. If there is not enough time to read all texts, let's select one simple FAQ page and translate it to all languages, according to this commit: https://github.com/organicmaps/organicmaps.github.io/pull/185/commits/a997f3ce1e3e2e04d5cdf19f3b5301fabf788080

Existing content can stay on this or another branch, and then we can continue improving it after rebasing to the master branch with the ready structure.

[rtsisyk]

Please push a branch with 1-2 FAQ articles for the beginning, in English. I have been waiting for this new FAQ section for months.

[strump]

@biodranik I fixed FAQ templates little bit:

• Added translation for FAQ breadcrumbs
• Added RU translation for a single Android related question

Problems I see so far: you can't change language from https://faq-plus-tts.organicmaps.pages.dev/faq/ and https://faq-plus-tts.organicmaps.pages.dev/faq/android/ pages. Language selector (top right link) doesn't work with taxonomies, because those taxonomies have no list of supported languages. Only FAQ questions have language selector (if translations are available).

I'm little bit lost with next steps. What structural changes do we need? What text related changes do we need?

[gpesquero]

I've fixed PR 204 so the FAQs also work now for Spanish language.

One issue that I've noticed in the resulting FAQ list in Spanish...

...is that the "Aplicación preguntas" text is incorrect, as it comes from the direct composition of the translation of the taxonomy name "App" and the string "questions". In Spanish (and in many other languages), the word order shall be the opposite ("Preguntas (de) Aplicación").

This taxonomy+question word order comes from the code <h3><a href="{{term.permalink}}">{{term.name}} {{ trans(key='faq-questions', lang=lang) }}</a></h3> in the file templates/faq/list.html. Could it be possible to have different versions of this file for every/some languages to arrange correctly the word order?

[biodranik]

@gpesquero yes, you can add something like {% if lang == "es" %}{{ trans(key='faq-questions', lang=lang)}} de {{term.name}}{% else %}{{term.name}} {{ trans(key='faq-questions', lang=lang) }}{% endif %}

[biodranik]

@strump did you try to set lang explicitly in taxonomy? Maybe dumping all available variables help to get list of translations?

If languages issue is fixed, then we can cleanup the code and merge it to the master. Do you see any other issues?

[strump]

@biodranik I can get the current language for a taxonomy, but I couldn't find all available languages for a taxonomy.

For example, "Android" taxonomy is currently available in two languages, while "Map" taxonomy has only "en" translation. But I don't know how to get a list of all available translations to enable language switcher.

Taxonomy+Translation = pain 😔

[biodranik]

@strump you can access all currently configured taxonomies and their translations from global var languages["ru"].taxonomies[], which may be similar to the already existing code that scans page translations.

But I don't think it's a blocker, let's focus on other issues and polishing the final version for merging, this fix can be done later.

[strump]

@gpesquero @biodranik maybe we should replace

faq-questions = "questions"

with somethink like

[languages.en]
faq-questions = "%1 questions"

[languages.es]
faq-questions = "Preguntas de %1"

What do you think?

[strump]

@gpesquero Let's try another option. I removed work "question"/"pregunta" completely. Let's use just taxonomy names as titles: "Android", "Map", "Routing".

And you can translate taxonomy terms: "Mapa" instead of "Map", "Ruta" instead or "Routing". Please try and tell how it looks now?

[gpesquero]

@gpesquero Let's try another option. I removed work "question"/"pregunta" completely. Let's use just taxonomy names as titles: "Android", "Map", "Routing".

This approach is simpler and will give us less "headaches", so it looks good to me...

PR 204 updated accordingly...

[strump]

@biodranik should I close this PR after #212 is merged?

[biodranik]

@strump I think yes, you did a lot of work, thank you very, very much!

It may make sense to leave content articles though for future updates/modifications.

[biodranik]

The FAQ structure based on this PR has already been merged. Only the content is needed now.