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.

...

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 spec before starting application developmentto 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 it 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

...

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 technical issue with CommCare.  The most It is 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 IDs in the column titles to see if 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, 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.

...

• 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 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>)

...

 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 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. Add filters for case properties to allow the user to filter what they see in their case list (in progress)

Multimedia

...

i.e. they enter the name of a village and see only cases from that village).

Be careful about designing case management screens. You ant to limit the # of case properties that are shown in the list view 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 why you are going to use it.

• 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 volume 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.Pictures:
• See more detailed recommendations in our Audio Recording Guide.

Images:

• If possible,

...

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

• If there are multiple single select questions in a row, its important to change the image for each picture. If the image is the same, its 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 asking questions that can provide the information you need.
• Do a data export to see what data is automatically captured and don't ask anything you don't need to. For example, the userid is 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

...

• 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.

...

Text input is the most time-consuming and error-prone type of question. Wherever possible replace text questions with single select questions. If there are a lot of options consider breaking it down into several shorter lists (i.e. first ask which village, then depending upon that answer ask which part of the village).  Text input questions are especially difficult for any illiterate CHW. Where possible these questions should not be required and there should be a workaround to gather the information.

NUMERIC INPUT

(in progress)

DATE INPUT

(in progressMake sure you choose carefully whether you want an integer or decimal number if you data and choose the question type accordingly.

Keep in mind that neither integer nor decimal questions keep leading zeros. If you need to maintain leading zeros choose text input (see Common Logic and Calculations). 

In the near future there will be a new "phone number" question type that will allow you to store long integers, but until then, if you want to store a number greater than 8 digits, you should choose "text" input. By editing the xml you can make the number keyboard show on the screen, instead of the alphabetic keyboard.

If you need to have a number of a specific length (i.e. for an ID number), put a string-length constraint on the question (see Common Logic and Calculations)

MULTI-SELECT

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. 

...

Logic Properties

(in progress)

Validation

(in progress)Creating a validation condition for input-type questions can be very useful as a way to minimize the risk of users entering erroneous data.  However, you should keep the following in mind:

• Validation conditions should always be accompanied by descriptive constraint messages that will clearly inform the user what they need to correct. You can also add audio to constraint messages. For example, you may want to put a limit on a birth date to make sure the user doesn't accidentally put a date in the future.  But if you don't put a constraint message the user may not understand why their answer was not accepted. This can be very frustrating for the user.
• You want to be careful about your validation - if there is data present in the field that doesn't fit your validation rule, this could prevent your app from being used. Make sure that your conditions are realistic and consider allowing an extra margin on your allowed values to permit extreme cases.

Display Logic

(in progress)

...