Write accessible documentation

Always aim to write content that all users can access and understand, regardless of background or ability. Although most of these guidelines aren't new to this style guide, they make content accessible for all audiences, with or without disabilities.

Keep the following guidelines in mind when writing accessible documentation.

Writing

Write using plain language, simple sentence construction, and short paragraphs. Complex sentences and long paragraphs can be daunting for some users, such as those with reading disabilities or low vision, or for those who use translation tools. Plain language offers a smoother reading experience for all users. For example, users with screen readers can process text more quickly when sentences are concise and direct.

Avoid using complex words, such as jargon or complicated terminology. When you need to use terminology, use it consistently. For more guidance, see Use plain language.

Avoid directional or visual language

Language that relies only on direction, color, shape, or pattern doesn't help users with visual disabilities or those who use screen readers. Aim to remove this language from your documentation, and add language that isn't dependent on visual cues to help the user figure out where to go.

When directing users to a location in your topic, avoid using language like "above", "below", "left", or "right". Use "following" or "next" to notify users about a page element that follows directly after the sentence. Use "earlier", "later", or "previous" to describe information or page elements that precede or follow the user's current location.

If you can't provide the information the user needs in the current paragraph, include a descriptive link to the location. If you are referring to the next paragraph or section or to the preceding paragraph or section, it's okay to use "following", "next", or "previous" without a link.

The following examples show how to direct a user to content within the same topic:

Correct	Incorrect
The following table shows examples of inputs.	See the table below for examples of inputs.
For more information, see Headings later in this topic.	For more information, see the section at the bottom of this topic.
For an example of a multishift schedule, see the next scenario.	See the section right below this for an example of a multishift schedule.

When you must guide users through a task in the UI, refer to UI elements using their labels whenever possible. Avoid relying on directional or visual language as the only means to guide users to a location. Typically, directional language isn't needed to guide users through a task, but it's okay to include directional language in your instructions if the user might have trouble finding a location in the UI solely by the label.

Lead into new page elements

Page elements include tables, lists, images, videos, searches, commands, and code blocks. Always introduce a new page element using a lead-in sentence that explains what information the element contains or what the user needs to do. A lead-in sentence prepares users with what to expect from the upcoming page element.

Spell out words and symbols

Screen readers don't always refer to symbols using terms that fit the context of the sentence, so it's important to define symbols carefully in writing. Avoid unnecessary abbreviations or acronyms, especially those that don't closely match the words they refer to.

In general, use words instead of substituting them with symbols for clarity. For example, spell out words like "and", "plus", "minus", and "about" instead of using their respective symbols. Rather than using the right-pointing angle bracket to describe menu paths, use an equivalent word like "then". See the following table for examples:

Correct	Incorrect
Apps and add-ons	Apps & add-ons
Begin your time offset with a plus ( + ) or minus ( - ) to indicate the offset from the current time.	Begin your time offset with +/- to indicate the offset from the current time.
It can take up to about 5 minutes for your host to display in the user interface.	It can take up to ~5 minutes for your host to display in the user interface.
In Splunk Web, select Settings, then Advanced Search.	In Splunk Web, select Settings > Advanced Search.

Spell out all symbols in text if you must use them. See Show symbols in text for more information.

If you're writing UI text and you don't have space to write out the name of the symbol, use hidden text such as the aria-label attribute to define the symbol. For more guidance, see Abbreviations and Acronyms.

Be precise

When using pronouns that point back to or substitute for a noun, consider whether the noun that the pronoun refers to is clear. If the referent is unclear, too broad, or located far from the pronoun, the sentence can be vague or difficult to parse for users with reading disabilities.

Avoid capturing vague or broad ideas using pronouns like "this" or "these" without additional clarification. Make sure that relative pronouns, like "who", "which", and "that", modify the nearest noun. If a pronoun can have multiple possible referents in a sentence, always specify that referent in your writing. See Pronouns for more information.

The following table contains examples of vague sentences and more precise alternatives:

Vague	Precise
This eventually leads to the job expiring.	The job eventually expires after the search object is removed from the queue.
This is similar to the algorithms used for online shopping websites, which suggest related items based on what items other customers viewed or purchased.	This algorithm functions like an online shopping algorithm, which suggests related items based on what items other customers viewed or purchased.

Headings

Use headings to break up long paragraphs and help screen reader users navigate through the topic. Descriptive titles and headings are crucial to helping all users find the information they need.

For example, many screen reader users tab through headings first to figure out where they need to go. Users with reading disabilities find sections organized by headings easier to parse than long sections with fewer headings. The more descriptive and organized your headings are, the easier it is for users to orient themselves and navigate through your documentation.

Organize your topic using headers down to the H3 level. If you need to use a heading level beyond an H3, your topic might be too complex. Never skip heading hierarchy levels. For more guidance on headings, see Manual names, topic titles, and section headings.

Images

Images can help sighted readers understand complex workflows, refer to an icon, or view a portion of the UI, but they must include surrounding text to be meaningful for users with visual disabilities. If possible, replace images with text instead. When you create an image, check that the image reinforces the understanding of the surrounding text and includes alt text.

Users with visual disabilities need alt text to perceive images with a screen reader. Users who are neurodivergent might use screen readers to assist their understanding of various types of images. Users who don't speak English as their first language can use tools to translate alt text for images that include English labels. All users rely on text that accurately and thoroughly describes every image in Splunk documentation.

Follow this guidance when using images in your documentation:

• Don't include new information in an image. Introduce new information in the surrounding text of the image.
• Don't rely on color to convey the message of the image. Use a combination of colors, shapes, patterns, explanatory text, and labels instead.
• Ensure your image meets the contrast ratio for users with visual disabilities. See https://webaim.org/resources/contrastchecker/ on the WebAIM website.
• When including screenshots in your content, be sure to capture the UI while using the light theme with your screen zoomed to 100%. Don't use the dark theme.
• Always include alt text. For guidance on writing alt text, see Include alt text.
• Lead into an image with a description of the content and the purpose of the image that makes the image meaningful.

For more guidance on using images, see Best practices for including images.

Videos

Always include captions and transcripts with videos. Synchronize captions with the video and include all dialogue and important sound effects. If your video covers important visual details, make sure to describe them in your voice over.

Tables

Keep tables as simple as possible. Complicated tables that contain lists or merged cells are difficult to navigate using a screen reader. If you need to leave a table cell blank, add a nonbreaking space to the cell instead of leaving it empty. For more guidance on using tables, see Best practices for including tables.

Lists

Keep lists and sublists simple. Ensure that each item in the list uses parallel construction. Don't include more than one item, idea, or action in a single list item. Long, complicated lists that don't follow a consistent pattern hamper users with screen readers and can confuse those with reading disabilities. For more guidance on using lists, see Best practices for writing with lists.

Linking

Always make sure the purpose of the link is as clear, descriptive, and meaningful as possible. When you lead into the link with a description, users can decide whether that link is useful to them.

Example

If you run Splunk apps with Splunk Enterprise, see the Splunk products version compatibility matrix to determine the versions that your apps are compatible with.

For more guidance on linking, see Best practices for including links.