Page Comparison

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.

APPLICATION PLANNING

We have created an excel template that we like to use as an application spec. It's proven useful for defining and sharing the proposed application before starting to build it. 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 the contents 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 and discussing.

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 IDs and item labels. When you export your data the question ID/label is the only way you will be able to identify your data. Having long question IDs does not cause any technical issue with CommCare. It is critical 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" (under advanced) and then look at the question IDs in the column titles to verify that they make sense on their own.

 Here are examples of how question IDs can be very descriptive:

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 form, then 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, your data 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>).  See "Loading Case Data" in the Beginner's Tutorial

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 phone's screen.

 If you have modules that have forms with the same function (i.e. registration, referral, etc.) they should have similar names and be in the same order in both modules.

Case Management

Case management, and associated settings, are what make CommCare uniquely useful. It is important to spend some time considering how the users will navigate through the application and what they will be able to see about their cases. Pick two or three major details about a case that the user can use to distinguish and locate cases in their case list. You can also add filters for case properties to allow the user to filter what they see in their case list (i.e. they enter the name of a village and see only cases from that village).

Be careful about designing case management screens. You want to limit the number of case properties that are shown in the case list view (usually only two or three) and order them such that the most important ones are at the top of the detail view.

Multimedia

Before deciding to include multimedia in your application, think carefully through what the role of multimedia will be in your application.

• Are the images and audio recordings for the person using the phone, or for that person's client? This is particularly important for audio, because the language should be consistent with the intended audience.
• Do your users want multimedia?  Sometimes users, especially advanced or highly trained users, will not want any multimedia because they have extensive training in how to deliver messages/counsel their clients. Before preparing multimedia for an entire application, work with your user base to gather feedback and test your multimedia.
• What environment is your application going to be used in? If it is going to be used outside and images do not show up well on the phone you are using, then either the images have to be edited appropriately or should not be included. If it is a very loud environment make sure you maximize the volume in your recordings and test out playing the audio in the environment.

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.
• Official health messages are often written in very formal language. When making recordings, try using colloquial language that will be widely understood by the intended audience.
• See more detailed recommendations in our Audio Recording Guide.
• Have all the audio scripts defined, reviewed and approved by the partner organization prior to completing the recording. 

Images

• If possible, consider using a local illustrator.  Use the actual uniforms/dress of local health professionals.

• If there is more than one single-select question in a row, it is important to change the image for each question. If the image is the same, it's easy for the user, especially illiterate users, to get confused or think the application is not working properly.
• User-test your images- sometimes what you may think is a clearly understandable symbol may not be understood by users or their clients. For example, in one case an artist drew a digital thermometer and only upon asking users did the designer discover that they all thought it was a pen, not a thermometer.

Video

We haven't used video very much yet, so give it a try and post your recommendations here!

Data

• Sometimes data is treated as an afterthought to design of the application. However it is important to keep in mind what data you will want to see at the end and make sure you are designing your application and asking questions that can provide the information that you need. For example, it is possible track referrals or children of a given client without using subcases (by using case properties and filters), but if you do use subcases, it may be easier later on to analyze referrals and children data, when it is time to export that data and analyze it. 
• Do a data export as part of your testing process to see what data is automatically captured and don't ask anything you don't need to. For example, the user ID is automatically captured, so it might not be necessary to ask the user to enter their ID.

CommCare Settings

• For low literate users, it is best to use "CommCare Sense" mode, which can be configured on the main Application page under "CommCare Settings"
• In multi-lingual apps be sure to translate any user-interface strings that are not already translated (i.e. "form is loading", "back", etc.)

Language Support

...

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.

APPLICATION PLANNING

We have created an excel template that we like to use as an application spec. It's proven useful for defining and sharing the proposed application before starting to build it. 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 the contents 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 and discussing.

Download the Example Spec

APPLICATION DESIGN

Question ID and Case Property Naming

Have descriptive and consistent naming for your Question IDs and case properties. They are used in data exports and when doing case configuration.  

• Descriptive: Use something like date_of_birth not dob.  CommCare allows for long names if you want to be descriptive.  Another person should be able to looks at your names and understand the data. 
• Consistent: 
  • Be consistent with casing (i.e. always use lower case) 
  • Use the same name for the same question in different forms and the same case property name in different forms
  • User underscores instead of spaces (as spaces are not allowed)

To test your Question IDs, choose "export form contents" under Tools to view all questions in your form.   

Naming Conventions: Modules and Forms

Users will navigate the application using form and module names.

• Names should clearly describe what the module or form does 
• They should be short names (fit on one line of the phone's screen)
• Use the same name for forms with similar functions (ex. registration in different modules)

Case Management

Case management is what makes CommCare uniquely useful for front line workers.  Some important things to consider:

 Case List 

• Show maximum of 3 case properties in list
• Show properties that will help user find the case they want
• Add sorts(Case List Sorting) and hidden properties to help user search for the item they want. 

Case Detail

• Can show more properties than case list.  
• Add properties that will help user make sure they've picked the right case
• Add properties that will help user before opening a form for the case 
• Use the Format option to display case properties correctly for the user Date Formatting,etc.) See Case List and Case Detail View Configuration.
• Use ID Mapping if displaying any case properties that store item values.  This will make sure friendly text is shown.  

Multimedia

Before deciding to include multimedia in your application, think carefully through what the role of multimedia will be in your application.  Some applications may not need multimedia (pure data collection or advanced users who don't need support).  

Audio:

• Audience: Is the audio for the person using the phone or the beneficiary.  This changes the message and phrasing of the audio. 
• Counselling vs. Support: Do you want to use audio to help user answer a question (for low literate users) or as counselling for the beneficiary.   
• Environment:  If the audio is going to be played in a loud area, you may need to increase the audio volume. 
• Language and Dialect: Try record audio from someone who speaks the local language/dialect.  Use simple language that users/beneficiaries will understand. 

Images

• Local Images: Use a local illustrator so that images appear local to the area.
• Unique Images: If images are being used for low-literate user support, try make each image unique.  This will be less confusing.  
• Test Images: Test images! Images you may understand may be confusing to beneficiary or user.  For example, a digital thermometer picture may not be understood by all your users.  

Data

If data is important for you application, design your questions and case properties accordingly.  Thinking through what you want in the data will help inform the application.  

• If using case exports, add indicators you care about to the case (either by calculating them in forms or just saving some form questions to the case)
• Depending on what you need to track, decide on subcases for children, referrals, etc. vs. storing all data in a single case type
• Test your exports!  While building the app, test the exports to make sure that you're capturing data you need and nothing that isn't essential  For example, date that form is filled out and user ID is automatically captured. 

CommCare Settings

• Turn on CommCare Sense Mode For most applications, this will result in a simpler user experience for low literate users.  Some advanced features may be hidden (ex. Saved/Incomplete forms on CommCare Android)
• Turn on Two-Way Sync:  This will let ensure that if cases are reassigned, the user will be able to load them on their phone. 
• Setup Daily/Weekly Sync: If you're using case sharing, make sure you have daily or weekly sync on your phones so that users have a fresh version of any cases. 
• Set Text Input for Java Phones: Set to Native for non-english typing or full screen for QWERTY.  
• For Java Phones, set CommCare version to the latest available (indicated by a *)

Language Support

• For multilingual applications make sure each of the following is translated:
  • Question labels/display text in a form
  • Names of forms and modules
  • Any informatoin displayed in the case list and detail (including ID mapping)
  • User Interface translations (User Interface Translations) for your language.  Common language (ex. back, form is loading) should be updated.
• Set the default language of your application before creating your released build.  Drag and drop the languages and put the default language at the top.  

FORM DESIGN

Overall Form Structure

...

• 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 the user 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 (see the Beginner's Guide)
• 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.

...