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.