Writing for The VA App Store

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.