Add additional guidance hints

[MartijnR]

This feature has recently been added to the ODK XForms Spec. Rationale for the feature is described here.

To add this feature to pyxform, could we do something like this perhaps?

input:

type	name	label	hint	hint_print	relevant
int	a	label	normal hint	This question is skipped if the answer to ... is less than or equal to 5.	${num} > 5

output:

<text id="/data/a:hint">
    <value>normal hint</value>
    <value form="print">This ... or equal to 5.</value>
</text>

[lognaturel]

The structure looks good to me! Now that I'm seeing it like this, I'm wondering whether the attribute value could be called something more generic like "meta" or "comment" or "training". Seeing an example, I can imagine a mobile/web client showing these values under certain conditions. Apologies for not thinking of this earlier. print is ok by me too!

[MartijnR]

Haha, yes I agree actually. I has uses beyond making it visible only on printouts. Let's figure out what would make the most sense as an XLSForm heading and then decide whether we also need to change the XForm syntax or leave that as is.

cc. @tinok

[MartijnR]

"guidance" perhaps?

[tinok]

guidance sounds good to me. The initial idea was to have this visible in print views for use in offline training, since you wouldn't want these extended hints visible in the live form necessarily.

There is already a hint field that is always visible, which provides guidance to the enumerator. I'm not opposed to having this new field potentially show in the live form--it could be useful when training on a projector, for example. But then we'd need a switch in the form to show/hide them.

Here's an extended example:

label: Number of household members
hint: Including infrequent inhabitant
print/guidance/training: Also ask if there's any family member who infrequently lives in this household, defined as having slept there for 4 or more nights in the previous week. If that person did live there in the previous week but isn't going to come back in the following two weeks, do not count them. Household is defined as the family's main living space where members regularly eat together, even if one or more live in a separate structure. Extended families where people live in the vicinity but don't eat together are considered separate households.

[lognaturel]

Thanks for that example, @tinok. As screens on mobile devices get bigger, I can also imagine a split screen setup where the questions are on the left and the guidance is a kind of script on the right.

@yanokwa will you give us another sanity check before we finalize this?

[yanokwa]

I agree that people will use this for more than just printable text. To me, what y'all are advocating is another hint, so why don't we just put hint in the name so it's super clear? I think hint_long (and then also accept hint_short as an alias for default hint) would work for me.

Another option is to do something like what Wordpress does and support a <!--more--> tag that would allow for users to tap the hint to show more detail. To be clear, this would be we just have one hint column but support a magic tag inside. My guess is that Martjin will hate this...

I'm not a big fan of even more options in Collect to toggle this, but we can fight over that some other day.

[MartijnR]

do something like what Wordpress does and support a tag

I felt obliged to hate it but I cannot pretend. It's nice to avoid an extra column. So whatever is easiest for users, I agree with on the XLSForm side.

[tinok]

A counter argument for a <!--more--> tag would be that users may have a long hint but no short hint, so starting out with <!--more--> followed by the long hint may seem a bit awkward. But I agree it's nice to avoid another column (and many more columns in case of translations).

…

On Wed, Aug 9, 2017 at 3:59 PM Martijn van de Rijdt < ***@***.***> wrote: do something like what Wordpress does and support a tag I felt obliged to hate it but I cannot pretend. It's nice to avoid an extra column. So whatever is easiest for users, I agree with on the XLSForm side. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#142 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AApG57m3Zm78-fi9x-0wossI4qXZWaFUks5sWg-EgaJpZM4Ot87E> .

[lognaturel]

@MartijnR Does your comment mean that even if we go with <!--more--> in XLSForm you'd rather we have a different solution at the XForms level? That sounds like the right thing to do because it would be strange for older clients to show the <!--more--> tag within hints.

@tinok The long hint with no short hint case is a good one to explicitly bring up. A leading <!--more--> does make it look a bit strange but I think that if documentation explicitly calls it out it's not so bad.

[lognaturel]

I'm also wondering whether we should take a little step back and think a little about spec change ratification process as I described in this forum post. More brains are really useful for these kinds of changes and picking sub-optimal strategies can end up being really painful! I would never have thought of <!--more--> and I rather like it. Makes me wonder what else we might be missing.

[MartijnR]

Does your comment mean that even if we go with in XLSForm you'd rather we have a different solution at the XForms level?

Yes, definitely. I think at XForms level it's a matter of adding form="[TBD]" regardless of the XLSForm syntax we end up with.

[tinok]

Let's get some more feedback from others. @pld might have some smart ideas about this as well.

Another counterargument for the <!-...-> tag would be that so far every field in the XForm received a new column, which is messy, but that's how XLSForm works. Starting to split multiple fields into the same column is a deviation from that norm. So without a lot of discussion / feedback it would be safer keeping to the old approach of adding another column (e.g. hint-expanded).

Another problem with the approach is that older clients would all of a sudden show the print/guidance/expanded-hints on the screen of the app without an ability to hide them. The idea behind this is that they are hidden by default and displayed when/if necessary, e.g. for training purposes.

[lognaturel]

I'm now going to enter the realm of a broader philosophical discussion. Let me know if you think this should happen somewhere else.

My general sense is that there's no particular reason for XLSForm to map so closely to ODK XForms. In fact, XLSForm provides a great opportunity to introduce human-friendly abstractions without sacrificing the things that make XForms powerful and useful. As @MartijnR was mentioning here, the XForms approach would definitely be to add another value for the form attribute. There's just no particular reason to follow that here and we should try to come up with something that is as user-friendly as possible. It can then spit out the proper XForms.

[tinok]

Yeah, that is a bigger question and I completely agree with you. We went down that road for KoBo to implement easy ways of creating matrix/ranking/roster questions (which are sets of similar questions but that the user can now create more easily), but haven't merged this in with master yet for a lack of any engagement. We seem to head in that direction but it's probably not part of #142 anymore..

cc @dorey

[lognaturel]

Apologies, I think I may have derailed things with my suggestion to move to the forum. It would be great to have things in a single place for upcoming proposals but we're all here so let's try to get this done! If someone would prefer to first have a broader philosophical conversation somewhere, I am also happy to participate wherever that happens.

@pld I saw you liked my comment above, is that just general agreement that XLSForm should deviate from XForms where more convenient for users or specific agreement to the <!--more--> suggestion?

I am currently liking something like:
When a cell in the hint column contains <!--[ ]*more[ ]*-->, the text before it is always shown as a hint to users. Text after it may optionally be shown depending on the client and settings.

In verifying the spec-reality fault line, I confirmed that if something like <value form="more">A lot more hint than you wanted</value> is added to a text for a hint, current versions of Collect ignore it. I presume it's the same for Enketo. That confirms that on the ODK XForms side, adding an attribute value is a nice, backwards-compatible way to make the change (the value for form won't necessarily be more, we also need to decide that).

I also saw that the ability to show expanded hints has been a user request on the Collect side (getodk/collect#71) so I'm glad we're taking the time to make this a little more general than only for printing.

[MartijnR]

This has been added to the XForm spec now. See at the bottom of this section under form attributes: https://opendatakit.github.io/xforms-spec/#languages

I think, it is ready for implementation in pyxform with the <!--more--> XLSForm syntax.

[lognaturel]

@MartijnR it felt like enough consensus, right? I may try to take a stab at implementing this soon.

[yanokwa]

Now that we've had a year to let it sit, I don't know if I'm so excited about <!-- more -->. I know I suggested it, but it feels very disjoint and inconsistent when compared to a new column. Maybe @tinok was right all along?

[MartijnR]

I have a slight preference for a separate column, such as hint_guidance too.

[tinok]

After thinking about it for a year, I'm still going with a separate column. Ha.

[lognaturel]

Hehe, ok, then! That's ok with me as well. Now it sounds like consensus!