Universal App Help


#1

TL;DR: This suggestion outlines a way to provide Status users with non-intrusive help from all app screens, while keeping the content multi-language and at the same time making it accessible to other Status implementations (Stratus, Status-js).


For an introduction into something similar or some of the concepts behind this, see The Explainers Initiative.


Step 1: Helpdocs repo

We create a new repo status-im/apphelp with the following structure:

capture

Each folder name under “content” corresponds to a screen identifier in the app. Each locale folder contains the content in the matching language. Images are shared across different language versions of the content, and are thus common. When a localized version of an image is needed, it can have a suffix like diagram_es.svg and the es_ES/content.html file can reflect this.

Step 2: Configure an ID’s meta file

Each content file is only valid if declared as such in its meta.json file. This file looks like something like this:

"langs": ["en_US", "es_ES"],
"author": "Status Team",
"expanded": ["https://our.status.im/group-chat", "https://our.status.im/encryption-limits-performance"]

Taking into account the above file, we see that the Croatian (hr_HR) content is disabled, and if a user wants to find out more about a given topic beyond what’s in the content.html file they can access any of the other links (this value can also be an object, so that titles=>links can be supported).

More metadata can be added to these files, as long as a standard agreed-upon structure is followed.

Step 3: Why?

With this in place, we have gained the following abilites organization-wide:

Status In-App Help

A conditional help button can be added to the app to make better use of the huge forehead which currently only contains the Status logo. The Help button could appear if and only if there is a matching entry for the screen ID the user is on. For example, if I’m on the invite to group chat screen in the app which is identified as group-invite in the code, the logic can check the repo for content, see if the meta file declares the currently selected language as active, and renders the content in an overlay. Yes, this also means a Spanish-speaking user would get Spanish content because it would be easy to check the language selected in the app vs. the declaration in the meta file, and render Spanish content if activated. If not, then it defaults to English.

In-app multi-language non-intrusive help docs are a 10xUX upgrade.

Community Contributions

By keeping the repo public, we allow the community to contribute better explanations, additional languages for existing help files, fix typos, and more. Local chapter leaders - ambassadors in certain locales could organize hackathons with non and semi-technical enthusiasts, onboarding new Status users in a truly useful way - by having them read the docs well in advance of using the app and staring at it, confused. This is something open source projects frequently do - I’ve been to such events hosted by Mozilla, Nextcloud and Wikipedia.

Universal Help

The openness and highly standardized layout of the repo means that any implementation of Status (i.e. Stratus, Status-js) can implement the same help content in the exact same way. This keeps things consistent across platforms, preventing users from feeling lost on switching, and avoids bloating releases with this text content.

This gives us independence from any given CMS, freedom of content and ease of rendering anywhere - including desktop apps, the status website, different mobile apps of all kinds, even extensions in the chat. E.g. “/status-help group invites”.


I know this would be quite an effort, especially from the perspective of integrating it into the current app, but I do truly think it would be enormously helpful and contribute to the openness principle.


#2

Excellent idea and detailed view on how to implement. I think this fits core, at the same time knowing it will take time before prioritized issues are dealt with first. Maybe write an issue referring to this post to make sure it goes on the Core backlog for future reference and doesn’t get lost?


#3

Done.