UX: HMW help people understand markers better

[Sebastian-ubs]

As a user I want to get hints on existing markers what they mean and how they are used so that I can use them correctly.

Description
When people see markers in the text they might not know what they mean, e.g. \ms.
Design a way to give hints e.g. on hovering over the marker or showing the backslash menu. Also design a way to link or show the usfm description from there.

observed in TC learning session

[irahopkinson]

What is a "TC learning session"?

I would note that while this is a good idea should people be in the space of dealing with markers, the general plan in P10S is to allow users to get the results they want without having to learn anything about USFM or its markers.

[Sebastian-ubs]

tc = translation consultant

Yes, I agree that we want to have people use it without markers as much as possible. I assume there will be situations where they still have to check the markers (e.g. when the visual difference of representation is not clear enough) and other users that are used to look at markers, might still want to look at markers - yet they do not know all of them as we observed.

[tjcouch-sil]

Indeed we hope people don't have to explicitly interact with US* markers, but the meaning represented by those markers is as crucial as ever. I agree with Sebastian that it would be really helpful to have some kind of guidance for the user about different markers.

For example, a translator might be rather overwhelmed by the many, many options they have when they click the block-level marker dropdown or open the in-line marker dropdown (currently backslash in P9). There are only a few short words describing each marker. How do I know when to use s1 vs s2? What do they look like? There's so much useful information in the USFM docs that could be put in front of the translator. Not all of it is relevant for every translator; for example, some translators won't care about USFM itself and therefore won't care that the "Section 1 Header" is called s1 internally or that markers are represented by \s1 in USFM. But lots of other info is relevant.

This desire for guidance reminds me of the style guides or whatever that Biblica or someone has. They give out information to all their translators about which markers to use in what contexts and how to format this, that, and the other thing. Adding some kind of extensible guidance could be a good way to help get this content in front of users.

[tombogle]

It could also be helpful to suppress the display of styles that are definitely not appropriate in a particular place. For example, Hebrew subtitle (\d) is, I believe, only ever used in Psalms; Speaker Identification (\sp) is perhaps only ever used in Job and Song of Solomon; Parallel passage reference(s) (\r) are used only primarily the gospels and definitely only in places where there is a recognized parallel passage; Signature of the author (of a letter or epistle) (\sig) is used in only a few verses in a handful of epistles. Suppressing the display of these markers in inappropriate places obviously won't solve the entire problem of potential confusion, but it could reduce the amount of noise to a slightly more manageable level and reduce the temptation of users to select a style just because it makes the text look right.