Use plain language

Using plain language helps the widest range of users understand what you write. Remember that Splunk documentation readers are a global audience whose first language might not be English. Using plain language increases the chance that readers understand what you wrote the first time they read it.

Plain language also makes translation easier and documentation more accessible. For more information on how using plain language increases accessibility, see Write accessible documentation.

Consider the following tips for using plain language in your writing:

• Avoid obscure words.
• Use simple but complete sentences. Often, you can communicate the same message in 20 words instead of 50 words.
• Use indicating nouns to identify elements and knowledge objects to ground the reader in the product.
• Avoid abbreviations. For more information on abbreviations, see Abbreviations.
• Be consistent. Use the same term to mean the same thing in one topic as you do in another topic.

Avoid jargon and complex terminology

Jargon and complex terminology are terms that are specific to a company, profession, or field. These terms are often referred to as technical language and can confuse and frustrate readers, so avoid them whenever possible. If you have to use complex or unfamiliar Splunk-specific terminology, link to the term in the Splexicon instead of redefining the term. For more information on linking to the Splexicon, see Formatting links in Splunk documentation.

Consider the following tips to help you avoid jargon in your writing:

• Take into account your audience's level of knowledge.
• Consider if the user needs to know the term to understand the documentation.
• Refer to the Usage dictionary for examples of words and phrases that are unnecessarily complex and their alternatives. See the Usage dictionary.

See the table for examples of how to translate jargon into plain language:

Jargon	Plain language
Use the out-of-the-box settings.	Use the default settings.
You can deploy Splunk Enterprise on-prem.	You can deploy Splunk Enterprise on-premises.
Perform an execution of the process steps with a core focus of ensuring that the deployments don't conflict.	Make sure that no deployments conflict with one another.
Troubleshoot a needle-in-a-haystack case by searching for a specific trace.	Troubleshoot a hard-to-find case by searching for a specific trace.

Choose clarity over concision

Write in concise sentences with a straightforward tone, but always use indicating nouns to identify special elements or knowledge objects. Naming elements and objects removes ambiguity and grounds the user in the product and the instructions. Don't remove indicating nouns for the sake of brevity or to try to sound casual.

See the following table for examples of how to include indicating nouns:

Missing indicating nouns	Indicating nouns included
Do a GET.	Submit a GET request.
map_get() extracts nested values from attributes.	Use the map_get() function to extract nested values from the attributes field.
Auth header is included by default, unless noAuth is set.	The auth header is included by default, unless the noAuth flag is set.
If you use start.ini to define JVM arguments, add javaagent after --exec.	If you use the start.ini file to define JVM arguments, add the javaagent argument after the --exec option.
Run the following to start in dev mode: yarn run start	From the command line, run the following command to start your app in develop mode: yarn run start