U.S. flag

An official website of the United States government

Dot gov

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Https

Secure .gov websites use HTTPS
A lock () or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

Writing for The VA App Store

How to write well for the people who use your app.

Use Plain Language

Clear, concise writing improves a reader’s understanding. Aim for text that reads at a sixth grade reading level or lower and use fewer than half the words you would normally in print media.

Tips for plain language:

  • Write sentences that are short and contain only one main idea.
  • Consider words that your audience is likely to use when searching for the app, and include them in your page’s text. This will help ensure that the app appears in search results on the VA App Store and in search engines.
  • Use technical terms, abbreviations, or acronyms only if their meaning will be clear to your audience and if the nontechnical or abbreviated version of that term is lengthy. Define the term when it is first used.
  • Every demonstrative pronoun (for example, it, they, this, these, and which) should clearly refer to a particular noun. For instance, in the sentence “Download the app and restart your phone, and it should work,” it is not clear whether “it” refers to the app or the phone.
  • Avoid gendered pronouns (he, she, his, and her) except when referring to a specific individual. Instead, use they, their, and them. For individuals, follow personal pronoun preferences.
  • Avoid non-English expressions, terms, and phrases that may be obscure to readers. This can include common expressions in non-English languages such as ad hoc, faux pas, and et cetera.
  • Avoid underlining text to emphasize it. Underlines can be mistaken for a hyperlink. Instead, use bold text for emphasis.

Don't do this

This application is utilized by a provider when he is configuring a prosthetic for the patient after completing approved training courses and acquiring an authorization code. It is secured against disclosure of PHI/PII, is easy to use, etc.

Do this

Providers use the Prosthetic Programmer app to set up prosthetics for their patients. The app is secured against disclosure of personal identifiable information and protected health information. You must take a training course before using this app.


Structure Text

People tend to read around 20%–28% of a webpage, scanning to look for information rather than reading every word. Structured text enables users to quickly find information. It also makes your text accessible to people using screen readers.

Tips for structuring text:

  • Avoid long blocks of unbroken text. Headings, short paragraphs, and bulleted and numbered lists all make it easier for your audience to read your content.
  • Use concise and meaningful headings and subheadings to organize the text on your page.
  • Put the most important information at the top of the page and less important information lower on the page. VA App Store pages are designed to support this structure. Learn more in What to Include on an App Page.
  • Don’t overuse bulleted and numbered lists. Although they are helpful for breaking up a webpage, a page full of bulleted lists can overwhelm the reader. If you use lists, adhere to the following best practices:
    • Ensure entries conform to a consistent pattern and begin with the same parts of speech (for example, bullet points all starting with a noun or verb).
    • Capitalize the first word of every entry.
    • Use a period at the end of list items if the list items are longer than a few words.
    • Use numbered lists only when the order of the items is important, such as in step-by-step instructions.

Don't do this

This app offers appointment scheduling, Secure Messaging, symptom tracking, and medication reminders.

Do this

This app offers:

  • Appointment scheduling
  • Secure Messaging
  • Symptom tracking
  • Medication reminders

Write Effective Link Text

Links help readers navigate within and between websites. Good link text helps readers know the contents of the page before they visit it and makes pages easier to read.

Tips for effective links:

  • Avoid using the URL directly on the page without link text. Also avoid using vague link text such as “learn more” or “download.”
  • Use descriptive link text, such as the exact webpage title or document name that the link will lead to. This way, users will know what to expect and can quickly verify that they arrived on the correct page. This also improves search engine optimization because search engines value links that include full page titles (for example, “VA App Store” is better than “Our Website”).
  • Place links at the beginning or end of a paragraph or sentence. The reader’s eye naturally gravitates to blue hyperlinks. So placing links at the beginning or end of a paragraph or sentence improves readability and emphasizes the link.
  • Links should be used and not talked about. After years of use, readers instinctively understand hyperlinks. There is no need to call special attention to them. So avoid expressions such as “click here,” “website,” or “link.”
  • Check your links regularly to make sure they still work. Broken links damage your reader’s trust in the quality of your content. Visit Content Maintenance for more guidance on managing your app page content after it’s been published.

Don't do this

Click here for more information about VA telehealth.

Do this

For more on VA telehealth, visit the Office of Connected Care website.


Use Frequently Asked Questions Effectively

Avoid using FAQ on your app page if the information can be easily included elsewhere. FAQ make information harder for your audience to find and process because they duplicate site content, show information outside of logical order, don’t support scanning of the text, and often don’t include keywords. If you must use FAQ, use them to address user feedback and not as the main source of information about an app.

Tips for using FAQ:

  • Base FAQ on real user feedback (such as survey responses for help desk queries). FAQ should not be used for self-promotion or as a list of talking points.
  • Keep questions short and put keywords early in the question to support scanning.
  • Don’t create a question that is already answered elsewhere on your app page.
  • Keep your FAQ list short. The more questions you have, the harder they are to read and sort through.

Note: The VA App Store currently displays FAQ in one location on every app page. In the future, FAQ will appear integrated with related content.

Don't do this

How do I get help?

Do this

I can’t sign in. Whom do I contact?


Follow VA Style

All app content must follow VA.gov’s Content Style Guide and the VA Office of Connected Care Brand Guidelines.