SurveyCTO Style Guide

NOTE: While a majority of these practices are applicable for any ODK based-platform, this guide was drafted using SurveyCTO, so some features may not be applicable/available on all ODK based platforms.

Read First

• The DIME Analytics SurveyCTO Style Guide is part of the package, iesurveykit.
• The SurveyCTO Style Guide aims to establish the use of a standardized coding style for surveys in field research.

Overview

Data collection for field research typically involves highly complex questionnaires that aim to capture a wide range of information from respondents. While ODK-based platforms offer point-and-click methods for creating questionnaires, we recommend using XLSForms for programming survey instruments. The term “XLSForm” refers to an Excel file that is used for designing questionnaires, which can simply be uploaded to SurveyCTO and other ODK-based platforms. Throughout this style guide, our recommendations are based on working with XLSForms, as they are easily reproducible, can be developed both online and offline, and make collaboration within a team easier.

However, as more modules are added and questionnaires become increasingly complex, even XLSForms can quickly become unwieldy, and hard to read - for instance, imagine developing an XLSForm for a questionnaire that has 100+ questions! This necessitates a resource that allows both beginners and advanced programmers to efficiently program questionnaires that follow certain standardized coding practices. While programming languages like R and Stata have several style guides that help coders deal with commonly encountered tasks in a manner that is both efficient, and easy to follow, no such guidelines exist when it comes to creating easy-to-read XLS forms for SurveyCTO (and other ODK platforms).

The DIME Analytics SurveyCTO Style Guide aims to fill exactly this gap, and establish the use of a standardized coding style for surveys in field research. Adopting consistent style conventions facilitates re-use of forms across projects and improves overall readability and adaptability. By applying the guidance and tips provided in this guide, readers will learn to write and develop survey forms that are easy to understand and work with, regardless of their level of expertise in SurveyCTO/ODK. In addition, we have developed the DIME XLSForm Template to provide concrete examples of the recommendations provided in this guide.

This Style Guide broadly covers three categories of style aspects when programming an electronic survey using XLSForms:

1. Design and development. Deals with ease of reading an XLSForm during the design stage
2. User interface. Deals with set up of XLSForm programming that improves user experience when answering the survey
3. Exported form dataset. Deals with with set up of XLSForm programming that supports more efficient ways of working with the exported data

Design and development

As discussed earlier, we recommend using XLSForms to design and develop questionnaires for ODK-based platforms. While creating an XLSForm from scratch is possible, we recommend working with the DIME XLSForm Template to facilitate adoption of the practices discussed in this style guide. In this section, we discuss practices that simplify the process of designing XLS forms, and make it easier to follow the flow of a complex questionnaire.

Color coding of rows

Conditional color coding of rows based on field type makes it easier to review and identify different field types in an XLSForm. The DIME XLSForm Template demonstrates this color coding, where each question type has a specific color, and the same applies to calculate fields, and begin_ and end_ fields.

Consider an example where the constraint for all integer-type questions needs to be updated to make sure the values are not negative. In cases where there are multiple integer-type questions in the form, the coder has to go through each line to first identify the integer-type questions, and then fix the constraints for each of them.

The DIME XLSForm Template with built-in color coding of rows, on the other hand, allows for easier identification of each question type. In the example of fixing constraints for all integer-type questions, the coder can simply identify the blue rows, and then edit the constraint column for each of them to make sure age is always greater than 0.

Below we show the same section of an XLSForm twice, one with built-in color coding, and the other without color coding.