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.

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.

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.

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.

Follow VA Style

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

All app pages are designed to account for the following types of content. Aside from these tips, you should review Writing for the VA App Store and ensure that all content follows the VA Office of Connected Care Brand Guidelines.

If you need to include content on your app page that is not already accounted for in the standard app page template, do not place that content in a section that seems like the best fit. Email the VA App Store support team, and we will work with you to find the best placement and format for your needs.

Introduction (required)

All app pages need to start with an introduction that describes what the app is for and why it is valuable.

Announcement (optional)

If you have timely information for your audience, you can use an announcement. This is an optional page element that you can use at any time.

Features (required)

All app pages should describe the app’s features and functions.

Getting Started (required)

All app pages should provide guidance on how to access the app for the first time.

Training Materials (optional)

Training materials tell people how to use your app after they have successfully accessed it. Training materials are optional but may be useful for apps with complicated functions.

FAQ (optional)

FAQ should address user feedback and common questions about the app.

Release Notes (optional)

Provide important function changes made in the latest update of your app.

Known Issues (optional)

If your app has any bugs or issues, communicate them with your users. This transparency may minimize users’ frustration and ensure that they keep using the app. It also minimizes the number of complaints you receive on a given issue. Known issues are optional and should be kept up to date.

Help (required)

All app pages have a Help section that covers how users can get assistance in using your app.

Provide App Feedback (required)

All app pages have a mechanism for users to provide feedback about that app. The text used here is the same across all app pages, and app teams do not need to write any text to support this.

Your app does not need to appear under a filter option from every category, but it should appear under at least one filter or tag.

Apps should only appear under a filter if the app is directly related to that topic. For example, an app designed to guide Veterans through meditation practices may have positive effects on Veterans who have trouble controlling anger, but that app should not be tagged with “anger” because that’s not part of the app’s core purpose. Users who search for apps related to anger management would be surprised and confused to find a meditation app appear in their results. The tag “mindfulness, resilience, and goal setting” is more appropriate for a meditation app.

App teams should note what filters apply to their app when filling out the VA Mobile App Intake form (VA Network access required). If your app falls under a topic that is not included in the current filter list, we will discuss whether a new filter is needed.

Filter Groups

Mental Wellness and Self-Care

Filter names:

• Alcohol, Drug, and Tobacco Use
• Anger and Irritability
• Anxiety and Stress
• Depression and Mood
• Mindfulness, Resilience, and Goal Setting
• PTSD and Trauma
• Relationships
• Sleep and Insomnia

Physical Wellness and Health

Filter names:

• Brain Health and Strokes
• COVID-19
• Diabetes and Kidney Health
• Disaster and Exposure (Apps used in response to crisis events or their aftermath, such as exposure to airborne hazards.)
• Heart Health and Conditions
• Nutrition and Exercise
• Pain and Headaches
• Prosthetics
• Women’s Health
• Ulcers

Care at VA

Filter names:

• Appointment Scheduling
• Automatic Text Alerts
• Benefits (Apps that educate Veterans about VA benefits or help them access their VA benefits.)
• Health Education and Information
• Medication Management
• Scans (Apps used to scan or take images of the body, usually for prosthetics.)
• Virtual Communications
• Video/Virtual Visits
• Symptom Tracking and Screening
• Treatment Companion (Apps that supplement therapy sessions, either during or after the therapy appointment.)

Publishing Your App

Visit VA Mobile App Intake to learn how to publish a new app on the VA App Store.

When you need to update your app page content, submit a request by emailing the VA App Store support team. You should also email this team if you need to add content to your app page that is not covered by What to Include on an App Page.

Maintaining Your App

Immediate Changes

You should submit a page update request as soon as:

• You identify a broken link or a link that will be broken soon (for example, if the app page links to a non-VA website that is changing).
• You have a timely announcement .

Monthly

Every month, you should:

• Review customer feedback. Does the feedback call for any changes to the FAQ or other content?
• Review your page content for broken links.

Annually

Every year, you should do a full review of your app page. Is any information out of date? Is there anything you can streamline or improve?

Retiring Your App

If your app no longer functions, submit a request to remove it from the VA App Store by emailing the VA App Store support team. Submit your request in advance if the app page should be removed by a particular date.