Write accessible documentation

Always aim to write content that all users can access and understand, regardless of background or ability. These guidelines make content accessible and usable for all audiences with or without disabilities.

To create accessible documentation, keep the guidelines for these categories of content in mind:

• Writing
• Headings
• Links
• Tables
• Lists
• Images
• Videos

Writing

When you create documentation, follow these accessibility best practices for writing.

Write in plain and inclusive language

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. In addition, biased language can deter users from reading the documentation and using Splunk products. Plain language ensures that all users can process text more quickly. Inclusive language ensures your documentation is fair, neutral in tone, and welcoming to all communities.

Follow these guidelines to write approachable and accessible documentation:

• Write using plain language, simple sentence construction, and short paragraphs.
• Write using inclusive language by choosing alternatives for biased terminology and by aligning with disability communities on language preferences. See Write unbiased documentation.
• Avoid using complex words, such as jargon or complicated terminology. When you need to use terminology, use it consistently. See Use plain language.
• Avoid writing tasks in paragraph form. Instead, use lists to organize tasks. See the Lists section in this topic.

Avoid directional language

Language that relies only on direction 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 spatial cues to help the user figure out where to go.

When directing users to a location in your topic, avoid using directional language like "above", "below", "left", or "right". Instead, describe the page element based on temporal relationships, such as whether it comes before or after the current sentence.

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.

Review the following table for examples of how to reference different locations within a doc topic:

Temporal relationship	Word options	Do this	Don't do this
Before the current sentence	Earlier, previous	For more information, see the Writing section earlier in this topic.	For more information, see the Writing section above.
Following directly after the sentence	Following, next	The following table shows examples of inputs.	The table below shows examples of inputs.
Further in the topic	Later	For more information, see the Images section later in this topic.	See below for information on images.

If you must guide users through the UI, refer to UI elements using their labels whenever possible. Avoid relying on directional 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.

Review the following table for examples of guiding users through the UI:

Do this	Don't do this
Select a value from the Zone drop-down list in the top-right corner.	Select a value from the drop-down list in the top-right corner.
Select an asset you want to configure from the Actions panel on the left.	Select an asset you want to configure from the upper-left panel.

Combine color with other elements

Color can often be a helpful indicator for sighted readers. However, users who are color blind or use screen readers might not be able to recognize color when it's used as the only identifying element. When referring to color, include other identifiers to help all readers find what you're describing.

Review the following table for examples of ways you can combine color with other identifying elements:

Do this	Don't do this
Select the red alert with high severity.	Select the red alert.
The tallest points on the time-series chart, indicated by yellow circles, are the outliers.	Outliers on the time-series chart are yellow.

When creating diagrams or images that have color, use a combination of colors, shapes, patterns, explanatory text, and labels instead of color alone. See Images later in this topic.

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 complete 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.

For clarity, use words instead of substituting them with symbols. If you must use a symbol as a noun in your sentence, spell it out first and then include it in parentheses with nonbreaking spaces. The HTML character entity for a nonbreaking space is  . See Show symbols in text for more information guidance, examples, and what to call symbols.

Rather than using the right-pointing angle bracket to describe menu paths, use an equivalent word like "then". See Brackets.

Review the following table for examples of writing out text equivalents instead of relying on symbols:

Do this	Don't do this
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 about 5 minutes for your host to display in the user interface.	It can take ~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.

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.

Be precise

When using pronouns that point back to or substitute for a noun, consider whether it's clear what the noun is that the pronoun refers to. 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.

Follow these guidelines when writing for precision:

• 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.

Review the following table for examples of precise and vague sentences:

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

Headings

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. With more descriptive and organized headings, all users can orient themselves and navigate through your documentation.

Follow these guidelines when using headings in your documentation:

• Use headings to break up long paragraphs and help screen reader users navigate through the topic.
• 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.

Links

Splunk docs include judicious links to supporting material and additional information. Lead into the link with a description so users can decide whether that link is useful to them.

Follow these guidelines when linking in your documentation:

• Make sure the purpose of the link is as clear, descriptive, and meaningful as possible.
• Use the exact topic title or section heading, name of the page, or name of the entity you are linking to for the link text. Don't paraphrase the linked-to topic name.
• Don't hide a link behind other words or actions in a sentence.

Review the following table for examples of linking:

Do this	Don't do this
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.	If you run Splunk apps with Splunk Enterprise, determine the versions that your apps are compatible with.
Use navigators and dashboards to monitor your Kubernetes cluster. See Monitor your Kubernetes cluster.	Use navigators and dashboards to monitor your Kubernetes cluster.

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

Tables

Keep tables as simple as possible. Tables that contain lists, merged cells, or other tables are considered to be complicated tables, and screen readers have a difficult time parsing and navigating the table contents.

Follow these guidelines when including tables in your documentation:

• If you need to leave a table cell blank, add a nonbreaking space to the cell instead of leaving it empty. The HTML character entity for a nonbreaking space is  .
• Avoid merging or splitting table cells. This typically indicates your table is too complex. Use a separate table or a different type of formatting to organize the additional information.
• Don't use X or another character to indicate compatibility or support. Instead, use Yes and No. See Spell out words and symbols for more information.

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

Lists

Keep lists as simple as possible. Long, complicated lists that don't follow a consistent pattern hamper users with screen readers and can confuse people with reading disabilities.

Follow this guidelines when using lists in your documentation:

• Keep lists and sublists simple.
• Ensure that each item in the list uses parallel construction.
• Don't include more than 1 item, idea, or action in a single list item.

For more guidance on using lists, see Best practices for writing with lists.

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 your image isn't visually valuable, replace the image 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 use English labels. All users rely on text that accurately and thoroughly describes every image in Splunk documentation.

Follow these guidelines when using images in your documentation:

• Don't include new information in an image. Introduce new information in the surrounding text of the image.
• Lead into an image with a description of the content and the purpose of the image.
• When using color, include other indicators to convey the message of the image. Use a combination of colors, shapes, patterns, explanatory text, and labels. To see an example of a diagram that uses other methods to convey information besides color, see Diagrams.
• 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 every image. For guidance on writing alt text, see Include alt text.

For more guidance on using images, see Including images in Splunk docs.

Videos

Users with visual disabilities require captions and transcripts with all video content. Users who are neurodivergent or don't speak English as their first language can also benefit from captioning.

Follow these guidelines when using videos in your documentation:

• 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.