SurveyCTO form design style guide

This is a guide for advanced users of SurveyCTO, so is biased toward spreadsheet form design. The SurveyCTO team follows these guidelines internally, as we believe them to be best practices.

SurveyCTO offers an incredibly flexible form design standard. Within certain limits, you can name forms, fields, choice list items, and server datasets however you like. However, consistency is the key to easily understandable form designs that generate user-friendly and consistent data across projects. We encourage you to consider this style guide as a starting point for your team's own SurveyCTO form design style guide.

This guide covers the following sections:

• General
• Spreadsheet form definitions
• Cases datasets
• Server datasets
• Enumerator datasets

General

• Titles: Short and descriptive. Should be easy to identify at a glance to distinguish it from other forms and datasets.
  
  Example 1: "Advanced CATI starter kit sample form"
  
  Example 2: "CHW - Consultation form"
  
  
• IDs: Similar to the title, but lowercase, symbols removed, and underscores instead of spaces. Add extra underscores if it makes it easier to understand. Abbreviate longer words if that makes it shorter while still being easily understood, but keep it lowercase.
  • For example, if the form title is "CHW - Household form", make the form ID "chw_household_form".

Some workflow files have other requirements, so be sure to check those out below.

See Spreadsheet form definitions for examples.

Spreadsheet form definitions

• Title: See General.
• ID: See General.
• File name: Start with "Sample form - ", followed by the form title.

For example, check out the files in this folder. There are two forms:

• • Sample form - CHW - Household form
  • Sample form - CHW - Consultation form

At a glance at the file names, you know they are for the CHW workflow, and you know which form is for which purpose. The form titles are the file names without "Sample form - " at the front. For the form IDs:

• • chw_household_form
  • chw_consultation_form

They are just the form titles but lowercase, with the hyphen removed, and underscores instead of spaces.

Field labels

• For instructions to the form's user, use full statements or descriptions (i.e. "Enter the respondent's name.", not "Name").
• For questions that the form's user should read out loud (research questions), end them with a question mark. Consider styling these labels in a different, consistent manner using HTML formatting. Make them as distinct as possible from instructions.

Field names

• Use descriptive field names (e.g. “name”, “age” instead of “q1”, “q2”, etc.).
• Use snake case instead of camel case or Pascal case.
  • For example, use "my_field" instead of "myField" or "MyField".
• Only use the 26 lowercase letters of the English alphabet and underscores. So, don't use uppercase letters, hyphens, nor periods.
• Must start with a letter.
• Use prefixes and suffixes (favoring suffixes) to help indicate that fields are related, such as if they are part of the same group.
  • For example, in the M&E sample form, on rows 21-25, all of the field names start with "last_", since all of those fields are related.
• Make good use of abbreviations to help make long field names shorter. Field names start to become long when they exceed 12 characters.
• Do not make unnecessary use of abbreviations for already-short field names where writing things in full would be more clear (there is a balance).
• Do not exceed 32 characters.

For more tips, check out this blog post.

Groups

• Group names have the same restrictions as field names, including that they must be unique inside the list of field names and groups.
• While end group and end repeat rows in a form design that ends a group don't need to be named, we recommend re-using the name for the opening row as the name for the ending row. This will not count as a duplicate and will help you keep track of groups and avoid unmatched begin/end statements.
• While we encourage the same sort of short and systematic names for groups as for fields, they can be much longer (if helpful) because, by default, group names are never included in exported or published data (unless you use SurveyCTO Desktop's feature to include group names).

Expressions

• Only use the SurveyCTO-approved functions listed here.
• Avoid long, complex expressions. Make sure expressions are easy to read and follow. Break them up into multiple calculate fields if needed.
• If the expression uses a string, use single-quotes instead of double-quotes. The exception is if the string contains a single-quote or apostrophe already.
• When checking the value of a select_one or a select_multiple field:
  • Always use the selected() function, even with select_one fields that only have one choice selected, just in case it becomes a select_multiple field later. (e.g. Use selected(${field}, '1') instead of ${field} = '1'.)
  • When checking for a static choice value, put the choice value in single-quotes, even if it is a number. (e.g. Use selected(${field}, '1') instead of selected(${field}, 1).)
• For calculate fields, use the "label" column to explain their purpose.
  • For examples, check out the calculate fields in the M&E sample form.

Constraints

• Always add constraints to integer and decimal fields with an upper and lower bound. 
• Always add a constraint for a date, time, or datetime field to logically constrain the response according to the context:
  • No dates in the future for birthdays.
  • No dates in the past for graduation dates, while blocking dates that are wildly in the future.
  • No times of day that are outside office hours.
• Always include a constraint message for all languages in the form that clearly explains how to satisfy the constraint.

Choice lists

• list_name values that are used only once in the form should be named after the form field that uses them. Otherwise, pick a short, descriptive name that explains the contents of the choice list, using the naming rules for fields.
• For choice lists, use numeric choice values, unless non-numeric choice values are important to the workflow.
  • For example, in this New facility form, the choices in the choice list "facility_forms" are form IDs that are published to a cases dataset, so they are not numeric. But, the "yesno" choice list still uses numeric choice values. 
  • As another example, in the CHW - Consultation form, (see "households" and "hh_members"), as per the product documentation.

"Other" text fields

• When choice lists include an "other" option that should be captured in a text field that is conditionally relevant, always make the label understandable by itself. i.e. Do not write "Specify", write the actual question (e.g. "Which is the other crop harvested in the summer months by this household?").
• When following a selection made in a select_multiple field, use this naming convention [original field name] + [other] (i.e. without an underscore). An example would be the select_multiple field named "crops" followed by an 'other' text field named "cropsother". This is to avoid a naming conflict with the automatically generated dummy binary values generated in exports.
• Alternatively, use the specify-other field plug-in.

Forms designed for case management

• Block users from opening case management forms from Fill Blank Form by adding a note field that is required with the relevance not(empty(${caseid})). Give the field an appropriate instructional label that explains that the form should be opened from Manage Cases. Make sure that other fields are not relevant if this expression evaluates as true to prevent skipping ahead.

Plug-ins to use

This may not apply to your organization. At Dobility, we want to exemplify and show as much of what is great about SurveyCTO as possible but you shouldn't introduce unnecessary dependencies into forms.

• Try to include at least one field plug-in in any sample workflow to help expose users to these capabilities. The following should easily fit inside most forms:
  • • specify-other
    • text-box
    • extrabuttons
    • table-list
    • table-grid

Other guidelines

• Always include an "intro" note introducing the sample form (title and overview). If the sample form is part of a supporting article, add a link to that article.
  • Make sure links open in new tabs using the HTML attribute target="_blank".
  • By default, name it "intro".
  • For an example, see the field "intro1" on row 30 of the M&E form.
• Divide related groups of fields with blank rows, so the form is easier to follow and read, and it is easier to understand which fields are related to each other.
• To make customization easier, use as few specific questions as possible. Keep to questions that are needed for the workflow.
• Consider adding an instance_name, especially in the context of case management.

Cases datasets

• Title: If the use case involves a special kind of cases (e.g. consultations in the community health workers use case), briefly describe them in the title.
  • For example, in the CHW use case, the cases dataset has the title "CHW consultations".
• ID: Should never be "cases" but could begin with "cases_" followed by something relevant to the workflow. Doesn't have to begin with "cases_". Use only lowercase letters and underscores.
• Files names:
  • Cases dataset definition files should start with "Cases dataset definition - ", followed by the dataset title.
  • Cases dataset data files should start with "Cases dataset data - ", followed by the dataset title.
• Data files should be stored as CSV files for immediate use.

Server datasets

For examples, check out the CHW server dataset files.

• Title: See General.
• ID: See General.
• Files names:
  • Server dataset definition files should start with "Server dataset definition - ", followed by the dataset title.
  • Server dataset data files should start with "Server dataset data - ", followed by the dataset title.
• Data files should be Google Sheets files (or whichever file type is preferred by your organization).

Enumerator datasets

• Title: If the use case involves a special kind of enumerator, briefly describe them in the title.
  • For example, in the CHW workflow, the enumerator dataset is called "Community health workers"
• ID: Should be different from “enumerators”. See General above.
• Files names:
  • Enumerator dataset definitions should start with "Enumerator dataset definition - ", followed by the dataset title.
  • Enumerator dataset data files should start with "Enumerator dataset data - ", followed by the dataset title.
• Data files should be Google Sheets files.

Enumerator datasets should only be created when they add value to the workflow. A good example of this is the Community Health Workers use case.

Do you have thoughts on this support article? We'd love to hear them! Feel free to fill out this feedback form.