(Maybe) document potential suprises involving user preference persistence
- Dominant language
- Python
- Stars
- 58
- Forks
- 160
- Avg merge
- 5d 11h
- Merged PRs (30d)
- 12
Description
Related: #689
Related: https://github.com/getodk/central-frontend/pull/1018#discussion_r1747633899
Once we have user preference persistence (#689) in, there'll be much rejoicing all round of course. Surely.
Yet there are some minor points of potential unwelcome surprise/confusion when multiple sessions are writing preferences; in a nutshell, when a new session is created or when the app is reinstantiated (eg page reload), the user ends up with a agglomerate of the settings that were persisted in the other sessions. Thus a ctrl-R may give you some preferences different from those in effect in the same browser tab just a moment ago, which may be surprising.
Consider the following flow of events:
1. User opens a Central session on, say, **tab A** (could also be browser A, computer A - anything that gives you a distinct frontend app instance).
2. User also opens a Central session in **tab B**.
3. User sets project sort order to alphabetic in **tab A**.
4. User sets project sort order to temporal in **tab B**.
5. User happily goes about their business in both tabs. No surprises yet. Normal in-Vue navigation within the app instances in **tab A** and **tab B** will stay consistent with the distinct preferences expressed earlier in these distinct instances (step 3 and 4). All consistent with expected expectations, all good! :partying_face:
6. Now, the user, for some reason, reloads (eg ctrl-R) tab A, in which they had expressed the **alphabetic** project sort order preference before, and which had been working with that sort order ever since they set it.
7. They are confronted with the **temporal** project sort order — because the preferences got reloaded from the server, and **tab B** has been the last one to write the project sort order preference.
8. This may go unnoticed, or it may be a surprise. It's not a disaster — it's just a display preference, no one got hurt, and it may even be a welcome phenomenon, depending on scenario. But depending on the scenario the user may or may not be aware that they had actually expressed the temporal sort order in **tab B**, so things may appear a bit spooky or buggy.
9. User may or may not expect to read something about preferences in the documentation before jumping to conclusions involving either bugs :lady_beetle:, cosmic rays and bitflips :zap:, or the supernatural :broom:.
The point of potential documentation would therefor be to clear up what's happening — which is great for those who seek out documentation after encountering the above phenomenon.
However, that's begging the question: who will actually seek out that documentation in that case, rather than shrugging and continuing on their way? I don't see how it can be more than a very minor disturbance of the workflow, **although this depends on what settings we are going to put in there**. Thus the utility of the documentation may be limited, because the target audience may not reach for it.
Plus, this kind of documentation doesn't really have a home yet in the ODK docs: intuitively it would belong under "Using ODK Central", yet those are all "how to do X" type articles — there's no clear place for "FYI: This is how this works, nothing you can do about it, but now you know" type articles (yet). :man_shrugging:
Contributor guide
Research direction
Start by reading related issue #689 and the discussion on pull request #1018. Determine whether the documented multi-session preference behavior has a clear home under "Using ODK Central" and what users need to know. Done means an agreed documentation scope and location for explaining the behavior.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100