Collect - collapsible training hints ("guidance")

What is the general goal of the feature?
Sometimes survey organizers want to share more information about the meaning or intent of a particular question. Hints can be used for this but they will always be displayed. A new hint form called "guidance" was recently introduced to the ODK XForms spec to represent a longer training narrative that isn't always wanted in the user interface. See

What are some example use cases for this feature?

  • During training, provide additional guidance about certain questions that is then hidden for data collection.
  • For long-running forms that don't need to be filled out very frequently, enumerators can optionally view extra details about a question to jog their memory on what they should say to their subjects.

In Collect, I propose adding a setting at the bottom of General settings > form management > form filling labeled Show guidance for questions. Possible options are:

  • No - this is the default. Any guidance text in the form is ignored.
  • Yes - the guidance text is shown below the hint text in blue italics so that it stands out.
  • Yes - collapsed - the guidance text is shown collapsed by default with the option to click to expand (e.g.

this would be a good feature, also if a comment feature too can be allow on a questions on a single select or multiple select questions so that the enumerator will have the chance of elaborating more on a question if the respondent is making a very important point on it.



There's a first pass at an implementation at, thanks to Joel for that!

Here is what it looks like if the setting is "Yes - always shown":

Here is what it looks like if the setting is "Yes - collapsed":

And after tapping on the (i):

It would be great to get some UI feedback. In particular:

  • The guidance hint text is smaller than the hint text. Do you like that? Alternately it could be the same size.
  • Do you like the (i) icon?

Guidance hints are supported as of Collect v1.15.0.


hi @LN can i get excel sample form for the "guidance"

1 Like

@Fabla XLSForm support is not yet available (see It will hopefully be out in the next two weeks or so. In the mean time you could add it to form XML. See ODK Collect v1.15 Beta for more.

When we enable enketo from forms created in xls the collapsible hints do not show. Any suggestions on how to make the training hints appear in enketo?

I'm not sure whether Enketo supports guidance hints.!forum/enketo-users would be the place to ask or @martijnr may chime in here!

In Enketo the guidance hints show up on print outs. You can test with this form and uploading it to (Preview in Enketo and then click Print button).

Does that already address your requirements @LaraVR? If not, we'd be happy to (find some small funding to) add a special training view to Enketo that displays the hints on screen (is collapsible required in that case?). Would that meet your requirements or do need these hints to be accessible during data collection as well?

Depending on how it is implemented, it may be up to the Form/Data servers (Aggregate, Central, Ona, KoBoToolbox) to make this feature available to users.

1 Like

Hey Martin and LN! Thank you very much for your support!
Indeed, the guidance planned for Aggregate in excel survey form shows when printing to PDF or other. However on the inverse order (above the "open for more information"). It is less likely that our users (farmers) would print it for our questionnaires are quite extensive, covering many complex questions. We want to facilitate, that they view it for the first time and the times they forget but through the questionnaire.

Would it be possible to put it on the shortmap this training view? Collapsible, hoover over, pop-up, whatever makes the syntax for building up easier. We don't need on data collection, just for the user interface and user experience.

Thank you once again!

Thanks @LaraVR,

From your description it does sound like you'd need this extra guidance to be viewable during data collection. We'll look into this. We've added a training view to the roadmap, but maybe we can change this to collapsible guidance that is always accessible.