This page outlines recommendations for designing and building useful CommCare applications. These are compiled from collective experience in app construction and are only recommendations. Individual projects could vary substantially and the overall best practice is to go through extensive user testing and piloting to identify and correct language, media, or work flows that are confusing.
This site is currently undergoing revision (9 JULY 2012)
APPLICATION PLANNING
We have created an excel template that we use as an application spec. It's proven useful for defining and sharing the proposed application spec before starting application development. If you choose to build your application first in the form builder/HQ, you can now generate a document very similar to the application spec. This is found in the form builder under “advanced” -> “export form contents.” You can then select all and copy it into an Excel document. Exporting or working with the content in an Excel document makes it easy to show the overall structure of a form, which is useful for sharing.
Download the Example Spec
APPLICATION DESIGN
Naming Conventions: Question IDs/Labels
It is important to have a consistent and clear naming convention for your question ID and item labels. When you export your data the question ID is the only thing you will see to identify your data. Having long question IDs does not cause any issue with CommCare. The most critical thing is that your names be descriptive. A good rule of thumb is that someone else should be able to look at your data and know exactly what each column means. If you want to ensure that your question ID/item labels are sufficiently identifiable you can export form contents and then scan the question ID column to see if they make sense on their own.
| Recommended | Not Recommended |
|---|---|
| mother_phone_number | mother |
| child_birth_complication | complication |
It is also important to be consistent with your case property names. If you are dealing with one property and call it woman_phone_number in one form and mother_phone_number in another there it will be much easier to accidentally have property names that do not match in the case configuration. As a result, the data will not be linked.
We also recommend the following for question IDs/labels:
- use underscores: spaces are not allowed and underscores make for easier reading
- use all lower case! The case property names are all case sensitive so if you use different capitalizations in different parts of your app, things will not link up
- avoid using symbols like "&" ">" and "<" in form names, module names, or display text without double-checking that they show up as intended (this should be fixed in the near future)
- when you are dealing with "previous" case property values, use a consistent naming convention (i.e. prev_<case_property_name>)
Naming Conventions: modules and forms
Your users will navigate through the application via the form and module names. As such, they should be clear and succinct. Avoid making form/module names that do not fit on one line on the screen.
If you have modules that have forms with the same function (i.e. registration, referral, etc.) they should have similar names and order in both modules.
Case Management
Multimedia
Data
CommCare Settings
FORM DESIGN
Overall Form Structure
General Advice:
- Take advantage of calculations in forms to minimize errors. For example, if you are asking for a birth date, add a label afterwards that shows the calculated age. This may highlight an error in date entry if the age appears different than what was expected.
Use labels to force the user to stop and verify their information. You can add a label that shows the user data they entered and encourages them to verify if it is correct (see Common Logic and Calculations ).
- Use groups to prevent writing the same display logic (and having to update it) for related questions. Groups also make it easier to manage large forms in the designer.
- Consider including a success/you're done with the form label as your last question. This can be particularly useful on J2ME phones by giving the user an opportunity to correct any errors and make it clear to the user that the form is ending..
Don't try to do too much in one form. If you make a simple form that is easy to use it has a higher probabilty of success than a complex one that tries to tackle too much.
Question Types
While selecting a question type may seem very straight forward, there are some interesting usability issues associated with different questions that are important to consider.
TEXT INPUT
NUMERIC INPUT
DATE INPUT
MULTI-SELECT
SINGLE-SELECT
GPS-COLLECT
Logic Properties
Validation
Display Logic
Required Question
Required questions prevent the user from moving forward in the form without entering a value. Be careful when specifying a question is required - if the user of the application cannot determine the value for a particular question (ex. they are transcribing from a paper form and the particular value is not filled in), this can prevent them from submitting any data. If necessary, you can add a follow-up question that asks why a particular value was blank.
Experience working with low-literate community health workers in India
- These users experienced challenges in understanding the concept of a multi-select option question. In this question, the user is able to select more than one option. The selected options are indicated by an 'x' in a box. The question asked the user to select all the immunizations that child had received to date, with an option at the end for 'none'. Many users selected all the options, including the 'none' option or skipped the entire question and selected no options.
Multimedia
- Audio: Involve representative from partner organization on site for recording session and/or a staff member who understands local dialect. Although scripts can be followed, presence of native speakers will ensure integrity of message content.
- Pictures: If possible, use a local illustrator. Use the actual uniforms/dress of local health professionals