AB really needs a proper onboarding / help / in app tips system

[agrogers]

I know this has been discussed before and if I recall correctly Tuomas was fairly strongly opposed to it. We talked about it here #1071 and added some primitive help. But there are now so many features that I am surpised when I stubmle onto them... and I watch the activity on GitHub. I would expect that the vast majority of users have no idea about many of the features. This is a shame because people are doing great work on the app but the majority, I think, never benefit from it. And some even give 1 star reviews because they don't understand how AB works - they expect it to be like the simplistic and limited apps they have used in the past.

My suggestion is still to:

1. Throw up a dialog that allows the user to step through the 100 odd tips i think is needed to introduce all the features.
2. Allow the user to choose NEVER show me this dialog ever again.
3. Allow the user to choose SHOW this to me on the next major release.
4. Allow the user to choose SHOW me a new tip every week.

This replaces the minimal help that is already in the app.
The content for it comes from the official documentation (that I suspect few people read).
It doesn't need to be fancy... although I like fancy.

This was needed in 2021. It is needed even more now. I am happy to contribute where possible.

[meichthys]

I agree. Power users may be willing to poke around and discover features, but new users are often left wondering. I wouldn't think about switching away from Andbible now, but when i first started I just could not wrap my head around the windowing system, and because of that I flip-floped Bible apps for a while until I went all-in on open source. New users however, probably don't care so much about open source, and may need some guidance. Making the app more accessible via an onboarding flow along with a bit of fancy would probably help.

[tuomas2]

In the AI era, this kind of feature has become more feasible — for example, the required tip strings could be auto-translated and then polished by Transifex contributors. That said, it's still a significant amount of work and would need more evaluation and analysis before committing to it. To be honest, I'm still not sure how feasible this actually is in practice.

A few thoughts on design, if we ever get there:

• It should be completely optional and easy to dismiss/skip at any point
• Accessible from the menu so users can find it later
• Could contain multiple separate tutorials (e.g. one for windows, one for bookmarks, etc.) rather than one monolithic flow

Our primary focus for user guidance remains the ReadTheDocs documentation, which I've started actively maintaining myself now that AI tools make it much easier to keep up to date. Ideally the tutorial content would draw from that same material.

If I conclude that this is actually feasible, and if there is sponsorship for the development work, collaboration with Andrew is likely possible — we've had great experiences working together before (e.g. the bookmark modal UI design). Andrew could help with designing the tutorial paths and writing the tips content, and we'd work out together what is realistic to implement.

I'll post another comment later with some preliminary thoughts on possible implementation approaches.

[meichthys]

@tuomas2, Even just an easily accessible link from the App to the ReadTheDocs would be an improvement.
Currently if someone downloads the app, they will not find the ReadTheDocs site unless they go to the github repo or the andBible website.

[tuomas2]

Preliminary technical thoughts on implementation

After some analysis of the codebase and discussion, here are the main considerations:

Core mechanism: ViewPager2-based slideshow

The most straightforward approach is a TipsActivity (or DialogFragment) using ViewPager2 for step-through navigation. The existing dialog infrastructure and settings persistence (CommonUtils.settings) are already in place and would support this well.

Translatability is a hard requirement

Since this would be a central onboarding experience, the tip content must be fully translatable. This means all tip strings need to live in standard Android string resources — a dedicated res/values/tips.xml — so they flow through the existing Transifex pipeline automatically. AI-assisted batch translation could cover initial translations across languages. The tip metadata (ordering, icons, categories) would live in a separate non-translatable config file.

The overlay/coach marks question

A guided tour that highlights actual UI elements would be significantly more effective UX-wise. However, the hybrid WebView/native architecture creates a real obstacle: many of the most important features (long-press on verse for bookmarks, bookmark dots in text, cross-references) live inside the WebView, which is opaque to native overlays. A full coach-marks tour across ~100 tips would also have a high maintenance burden as the UI evolves.

A pragmatic hybrid approach: a small set of native overlay prompts (5–10, using something like MaterialTapTargetPrompt) for the most critical first-time moments (opening the menu, split-screen, version picker), combined with a slideshow for the broader tip library.

Maintenance

Screenshots in tips would become outdated quickly, and would also not scale across the wide range of Android screen sizes and densities the app supports. Text-only tips written at a conceptual level ("each window has its own menu") rather than specific UI directions ("tap the icon in the top right") age much better and reduce maintenance burden.

Content structure

Rather than one monolithic flow, grouping tips into separate short tutorials (windows, bookmarks, workspaces, etc.) makes the content more manageable — both to write and to navigate. This also matches Andrew's suggestion about ~100 tips and aligns with the existing help topics structure.

[agrogers]

RE translations, I feel like helping only some users is better than helping none. Are most users English speaking - then the 'some' becomes 'most'. AI translations are possibly better than nothing. Or the languages that the tip is available in is flagged and so only those tips are displayed. Re content, I love single source documents. If we can turn add the tips to the documentation and pull them from there then that would be perfect. I know AB is supposed to be all offline, but just showing the readthedocs page inside AB would be all we need. For the majority of users, they are online and happy to access bible related websites. So again, helping most is better than helping none. Happy to help with design and content.

…

___________________________ *www.TenOutOfTen.org* <https://www.TenOutOfTen.org> ***@***.*** (+61) 0477 174 193 (Australia) (+95) 09 250018669 (Myanmar)

On Wed, 25 Feb 2026 at 02:05, Tuomas Airaksinen ***@***.***> wrote: *tuomas2* left a comment (AndBible/and-bible#3648) <#3648 (comment)> In the AI era, this kind of feature has become more feasible — for example, the required tip strings could be auto-translated and then polished by Transifex contributors. That said, it's still a significant amount of work and would need more evaluation and analysis before committing to it. To be honest, I'm still not sure how feasible this actually is in practice. A few thoughts on design, if we ever get there: - It should be completely optional and easy to dismiss/skip at any point - Accessible from the menu so users can find it later - Could contain multiple separate tutorials (e.g. one for windows, one for bookmarks, etc.) rather than one monolithic flow Our primary focus for user guidance remains the ReadTheDocs documentation, which I've started actively maintaining myself now that AI tools make it much easier to keep up to date. Ideally the tutorial content would draw from that same material. If I conclude that this is actually feasible, and if there is sponsorship for the development work, collaboration with Andrew is likely possible — we've had great experiences working together before (e.g. the bookmark modal UI design). Andrew could help with designing the tutorial paths and writing the tips content, and we'd work out together what is realistic to implement. I'll post another comment later with some preliminary thoughts on possible implementation approaches. — Reply to this email directly, view it on GitHub <#3648 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADKGTJVFJRFC3X3TXJAPI7D4NSRYJAVCNFSM6AAAAACV3DYQDOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTSNJUGMYDKMZVGI> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[tuomas2]

Using ReadTheDocs as the foundation for the help system

Building on the idea of linking to ReadTheDocs from within the app — I think we can go further and make it a first-class offline experience.

The core idea: an AndBible help module built from ReadTheDocs

ReadTheDocs documentation can be bundled as a recommended offline AndBible module (using AndBible's own module format, similar to how we handle other non-SWORD content). The app would suggest downloading it the first time help is needed. After that, it opens instantly without any connectivity. A custom help:// URL scheme would route help requests — on first use it prompts the user to download the module, and subsequently just opens the relevant section.

Help content would be displayed in BibleView like any other document — no new rendering infrastructure needed. For contexts outside MainBibleActivity (e.g. settings screens), a lightweight dialog-style WebView popup would handle the display.

Online fallback (optional)

As an optional addition, the same help:// links could fall back to opening the live ReadTheDocs site for users who prefer not to download the module — though this may not be strictly necessary.

Versioning and auto-building

The help module could be versioned alongside the app so a given release downloads the matching documentation snapshot. Better yet, the module build process could live directly in the ReadTheDocs repository and trigger automatically on documentation updates — keeping it always current without any manual packaging step.

Translations

I've been thinking about auto-translating the ReadTheDocs content to major languages using a sentence-memory approach (incremental translation updates — only changed sentences need re-translating). I already have a similar tool for another purpose that could be extended for this. This could make multi-language documentation genuinely maintainable with relatively low ongoing effort.

Why this feels like the right path

• ReadTheDocs is already the canonical documentation source we're actively maintaining
• Help links scattered throughout the UI become a natural onboarding system as the docs improve
• Long-term maintenance burden is low: documentation updates automatically flow into the in-app experience
• Doesn't require maintaining a separate tip/slideshow content system

Happy to discuss further.

[agrogers]

Single source docs is always a good option I think. So that has my vote.

Do you have metrics on how many people currently visit the docs site? If incorporated into AB that will increase to every user at least once. That provides plenty of motivation to improve those docs.

Re requiring the help to be downloaded and not included in the install, I don't like that idea. One of the first problems people can face is that nothing downloads - vpn issues or whatever. This is one of tips we need to educate people about.

If file size is not an issue then I would just include the whole docs. If file size is an issue then I would include a minimal one that can be substituted with a full size if requested.

The tips should be the first thing people see. And the first tip should be that they have NO bibles, commentaries or anything. They must download something in the language of their choice. (we should also say that the non free versions are not available for legal reasons).

Then BEFORE they download we should try and push them through a minimal introduction to Windows and buttons and bible verse selection.

RE actual tips, I think we might need specifically designed tips, or perhaps the doc page starts with a tip like first paragraph. So when that doc page is included, an appropriately sized tip is shown. Or maybe the doc itself can tag a paragraph as the tip and that gets displayed with a link to the full page.

RE translations, Ai generated translations are good to me. Have them include a note at top or bottom saying this is Ai generated and if you can improve them please consider helping.

RE guided step through with UI items highlighted, I think this is the Holy grail of onboarding but not really necessary. A highlighted screenshot works almost as well and works in docs as well.

RE making it a standard AB doc, do you also mean to display it inside a standard window or in a custom tip modal window?

[tuomas2]

Good points, Andrew. A few clarifications and thoughts:

On translations: The AI-generated translations would be auto-regenerated whenever the documentation changes, so they couldn't be manually improved by contributors in the traditional sense — the pipeline would just overwrite them. The quality should still be decent for most languages.

On bundling vs. downloading: My current thinking for the MVP is a recommended module that regular users would install without a second thought — presented prominently on first launch or when help is first needed, and offered in the user's own language. Depending on the final package size, it could potentially be a mandatory silent install for new users. Alternatively, the online ReadTheDocs site could serve as the default, with the offline module as an optional download for those who want it. Either way, I wouldn't bundle multiple language versions into the APK itself — that would bloat the install size significantly.

On display (answering your question): I think both approaches have merit. The most natural way to browse documentation is in a standard AndBible window — that's how all other documents work in the app, and it gives users the familiar navigation experience. However, for contexts outside the main view (settings screens etc.), a lightweight AlertDialog with its own WebView widget would be more appropriate. It could also work well even in the main view in some cases — perhaps making it optional (user can open help in a window or in a dialog) would give the best of both worlds. In any case, it makes sense to always allow accessing the docs from a regular window, since that's the native document-browsing paradigm.

[agrogers]

RE translations: Good point. What I meant was that we could suggest to them that they write the actual document entry by hand and then it becomes part of the main docs release.

RE bundling: I agree that docs could get large, esp with screenshots (do you expect those to be included?). Does "could potentially be a mandatory silent install for new users" mean it is included with the package? I think some tips must be available immediately after installation without needing to download anything extra because some people don't understand the downloading process itself, especially when it hangs or they can't get to servers. But this is very specific case so could be handled some other way.

Some users might also decline the full help package mistakenly or not select it because they don't know what they are doing. So I think we should force everyone to see the first critical tip with the possibility of seeing the remaining critical ones to get started.
My thought is - bundle a minimal set of critical tips - might just be 5 in total. If a user wants all tips then they can download the whole document. That document could replace the little critical one. 

RE display: Showing tips in the standard windows is a good option. But the tips are designed to help people understand the standard windows - so it feels a little cart before the horse.  And it is not what people would expect.. at least not how i see hint/tip/help executed normally. I think it needs to be more dominate and a no-brainer.

I have actually not thought much about how it should look. But here is my first thought. It is this dialog that I think must show up on top of the Easy Start window immeidately after the initial install explaining that this is feature rich app so you REALLY should read the first 5 tips, there are no documents installed yet, you need to download the ones you want, and if you see nothing there is an internet issue so check your vpn / wifi / data etc.

1. Buttons to navigate through tips
2. The text in the middle lets people know there are a lot of tips. Clicking it opens some sort of list where they can select what they want to know about. Ideally we rack what they have looked at and can show that visually.
3. Close closes.
4. Don't Show opens a dialog allowing the user to choose to never see tips again, see them on the next major release, once a week , on every new feature addition.
5. Globe to take you to the docs website.