NAMING CONVENTIONS

The following naming conventions for forms are recommended in order to ensure human readability of the data, and ease of analysis. These conventions are also fully compatible with the KoBo Excel Data Analyser.

Note that these conventions do not refer to the 'labels' which are what enumerators see on the screen, but to the underlying 'names' which are used to store the data and which appear in the aggregated dataset

In XLSForm, the Form ID appears in the 'form_id' column of the 'settings' sheet

In KoBo, it appears under Form Settings > Form ID

When deploying a survey form in KoBo, the form ID can be altered.

Country identifier (2 uppercase letters) + Survey acronym (3-6 uppercase letters) + Version Number (1-2 numbers) + 'R' + Revision Number (1-2 numbers)

CO = Colombia, MIRA = Multi-sector initial rapid assessment, Version 1, Revision 3

(see 'Versioning' for more information)

UA = Ukraine, HSM = Humanitarian situation monitoring, Version 2, Revision 7

Question names

In XLSForm, question names appear in the 'name' column of the 'survey' sheet.

In KoBo, they appear in Settings > Question Options > Data Column Name.

In the resulting dataset, they are referred to as 'Column Headers > XML Values' in KoBo Data View, and appear as the column headings of the exported data file.

Section identifier (1 uppercase letter) + question number (optional) + underscore + abbreviated question description (CamelCase)

Here, 'I' signifies the 'Introduction' section of the form, and 'FullName' a comprehensible shorthand in CamelCase for what the question is asking

Here, 'B' signifies the form's section B (demoninated as such on the paper version), 4.3 is the question number (as on the paper version), and 'VulnGrps' is a comprehensible shorthand for 'Vulnerable Groups'

In XLSForm, option names appear in the 'name' column of the 'choices' sheet.

In KoBo, they appear as the Value field to the right of each option (initially set to 'AUTOMATIC')

In the resulting dataset, they are referred to as 'Answer Values > XML Values' in KoBo Data View, and appear as actual data values themselves in the exported data file.

1. For all questions the responses to which can be interpreted numerically, or on a continuous scale (eg of severity):

2. For all questions where responses cannot be interpreted numerically:

Short expression (all-caps; without punctuation, spaces or underscores)

In XLSForm, list names appear in the 'list name' column of the 'choices' sheet.

In KoBo, they do not appear at all, and are allocated automatically

In the resulting dataset, they do not appear at all.

The only purpose of a naming convention for list names is to improve readability of the XLSForm definition itself, rather than the resulting dataset.

1. List of options used by one specific question only, where this question has a question number

select_one A4.3

2. List of options used by a question without a question number, or by several questions

option list description (all lower case, in plural where applicable)

select_one genders

Associated or linked questions

Questions are sometimes closely associated with each other, which may occur at any point because of the structure of the questionnaire.

There are also three cases where groups of questions are analysed together, for which standardised naming conventions are especially important: 'Or Other', 'Ranking' and 'Scoring'

More detail on how to implement these particular cases is documented in subsequent sheets.

Standard question name convention

Principal question root + underscore + option name

including the following options:

Disabled (specify disability)

Other group(s) (please specify)

text questions to specify particulars

A4.3_VulnGrps_OTHER

including the following options:

(in principal question only)

(see 'Ranking' for more information)

including the following options:

(also appearing in associated questions)

C8.1_CropDamage_RICE

C8.1_CropDamage_MAIZE

C8.1_CropDamage_WHEAT

C8.1_CropDamage_MANIOC

(see 'Scoring' for more information)

This shows how to add an 'other' option to your single-select or multi-select questions, allowing the user to choose and specify an option which is not on the predefined list

NOTE: Do not use the inbuilt XLSForm code 'or_other', which is not customisable for multiple languages

1. Solution using a separate page. Note differences between single-select and multi-select solution

2. Solution with prompt on same page. Note differences between single-select and multi-select solution

Note that in this case, the 'relevant' logical statement has no effect. In KoBoCollect/ODKCollect, questions appearing on the same page cannot become hidden or visible. 'relevant' conditions are only evaluated when a user advances to a subsequent page

This shows how to implement a ranking question, which allows a user to select which option from a single-select list to choose as 1st Rank, 2nd Rank, 3rd Rank etc.

It can also be used in multi-select questions (where it becomes a 'tiering question' - placing several different options into different tiers)

The solution incorporates an 'or other' functionality, implemented on a subsequent page

1. Single-select solution (ranking individual options)

This example shows a question asking for the first three ranks. The solution can be extended to additional ranks, though more than 4 is not recommended

Other (please specify on next page)

This shows how to implement a scoring question, which allows a user to assign a score to each of a number of different options.

It is visualised as a matrix, essentially a multi-select question where instead of simply 'selecting' or 'not selecting' each option, a user can choose from a range of alternatives such as 'None', 'Moderate', 'Severe' etc.

The solution incorporates an 'or other' functionality, implemented on the same page.

select_one frequencies

select_one frequencies

select_one frequencies

select_one frequencies

select_one frequencies

select_one frequencies

Using a separate sheet for cascading questions is advisable if you intend to use an external, varying data source for the selections.

However, if you are prepared to hardcode these cascading options into the questionnaire, embedding them within the choices sheet is a better approach

MULTIPLE LANGUAGES

The form can support many languages at once. For each new language, add a new column to every column used for user messaging.

User-messaging columns are 'label', 'hint', 'required_message' and 'constraint_message', but not all of these have to be present

For each user-messaging column, replace the column name with :

eg, the column 'label' becomes:

Once you are using multiple languages, make sure that ALL user-messaging columns have been qualified with the language name.

i.e. do not have one column called 'label' and another called 'label::Français', but ensure that the first column is correctly titled 'label::English'

The language labels are also the options which appear in the user's 'select language' drop-down list. So they should be comprehensible (don't use codes such as 'label::241')

Ideally, the language labels should appear as written in the language itself, to facilitate user selection (i.e. 'label::Українська' instead of 'label::Ukrainian')

Ensure that the same language labels have been added to all user-messaging columns which you are using

i.e. don't leave the 'hint' column in a single language if the 'label' column has multiple languages, and make sure that the same languages are used in the 'hint' column as for the 'label' column

Version control is extremely important in maintaining coherence between different versions of the same form, and the different datasets which these versions produce.

There are three different columns in which the version must be clearly identified on the 'settings' sheet:

Necessary to unambiguously communicate to the form designer, enumerator and data analyst which version is meant

Particularly useful to display the version in the KoBoCollect app (though not strictly necessary if the version is consistently present in the form_title)

Necessary to permit simultaneous data collection against different versions of the same form (as form IDs must be unique)

Use a version number consisting of two separate numbers, indicating a 'major' and 'minor' revision, or 'version' vs 'revision'

changes to option sets, small additions or alterations, correction of spelling etc.

large changes, addition of new sections, addition of other languages etc.

Express the version number in different ways as follows:

Title of the Form version 5 revision 2

(see 'Naming Conventions' for more information on form IDs)

default_language