Skip to main content

Writing in applications: Grammar, punctuation, and style

This document provides communication and writing guidelines for designing DHIS2 applications. Apps that follow these guidelines offer a consistent, unambiguous DHIS2 user experience.

General guidance for communicating with users is given in Content and communication. This document offers more technical patterns and guidance.

Internationalization​

These guidelines cover grammar and language rules for English. Where possible, use these guidelines when translating to other languages. However, the natural communication style of a language takes precedent over these guidelines.

Spelling, grammar, capitalization

Spelling​

  • Use US-EN spelling, as a general rule.
  • There are some terms in DHIS2, like organisation unit, that have adopted other spellings. In those cases, use the DHIS2 established spelling.

Capitalization​

Sentence case​

  • Throughout an application, always use sentence case.

  • Don't use title case unless referring to an application, person, or product.

    • ✅ Recommended: Use the Capture app to record patient data.
    • ❌ Not recommended: Use the capture app to record patient data.
    • ❌ Not recommended: Use The Capture App To Record Patient Data.

Interface elements​

  • Use sentence case for all interface elements.

    • ✅ Recommended: A button label, Add a patient.
    • ❌ Not recommended: A button label Add a Patient.

Referring to interface elements​

  • When referring to elements in an interface, like buttons or sections, use the same capitalization style that the element itself uses.

So, when referring to a button on screen that reads Add record:

  • ✅ Recommended: Press Add record to get started.
  • ❌ Not recommended: Press add record to get started.

All-caps​

  • All-caps, capitalizing all letters, can be used sparingly for headings and labels.
  • Never use all-caps for sentences or paragraphs of text.

Punctuation​

Quotation marks​

  • Avoid quotation marks in interfaces. They add visual noise and are rarely needed.

  • Don't refer to interface terms using quotation marks.

  • If using, always use double quotation marks ("").

    • ✅ Recommended: Press Update to see the changes in the visualization.
    • ❌ Not recommended: Press "Update" to see the changes in the visualization.

Periods​

  • All sentences should end with a period. There are a few exceptions:
    • List items fewer than 3 words.
    • Headings, subheadings, titles, and subtitles.
    • Interface labels, like the label of a form field or a checkbox label.

Serial commas​

  • Use a serial comma, a comma before and at the end of a list, as it's the clearest and least ambiguous choice.

    • ✅ Recommended: Add users, roles, and groups to the table.
    • ❌ Not recommended: Add users, roles and groups to the table.

Writing style

Concise, clear, and actionable​

  • Make sure text gets quickly to the point. Users scan an interface and won't read every word.

    • ✅ Recommended: Manage patient data with the new Capture app.
    • ❌ Not recommended: Welcome to the new Capture app. This app is a quick, easy, and simple way to manage your DHIS2 instance patient data.

  • Prefer short, clear language and terms.

    • ✅ Recommended: Share this table with others by adding their usernames below.
    • ❌ Not recommended: You can provide access to this saved analytical object by entering the usernames of the users you want to share with the in the username input in the table below.

  • Use keywords consistently. Don't change the terms used to refer to key elements.

    • ✅ Recommended: Add users in the table below. Users added here have default settings.
    • ❌ Not recommended: Add users in the table below. People created in this database have default settings.

  • Avoid referring to the DHIS2 data model (unless the app purpose is interacting directly with that model, like Maintenance app).

    • ✅ Recommended: Couldn't load events for this patient.
    • ❌ Not recommended: Couldn't load events for this tracked entity instance.

  • Start statements with verbs where possible. This draws attention to the usefulness of the text.

    • ✅ Recommended: Edit and manage metadata with the Maintenance app.
    • ❌ Not recommended: Maintenance app offers editing and management of metadata.

  • Don't use will where a simpler, more effective present-tense statement works. Will should only be used when making reference to the consequences of a user action.

    • ✅ Recommended: Items in groups are available to everyone.
    • ❌ Not recommended: Items in groups will be available to everyone.
    • ✅ Recommended: Importing items adds them to the database.
    • ❌ Not recommended: Importing items will add them to the database.
    • ✅ Recommended: All items will be deleted.
    • ❌ Not recommended: All items are deleted after this operation is completed.

Politeness​

  • Using polite terms like please, thank you, and sorry is unnecessary. These terms add visual noise without adding value.

    • ✅ Recommended: Click the Open button to get started.
    • ❌ Not recommended: Please click the Open button to get started.

Acronyms​

  • Remember, not everyone knows what an acronym means.

  • Introduce an acronym the first time a term is used.

    • ✅ Recommended: Add data element group sets (DEGS) to this group. DEGS inherit the default settings.
    • ❌ Not recommended: Add DEGS to this group. DEGS inherit the default settings.