Use plain language

Writing with plain language helps the widest range of users understand your content. 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.
• Identify all elements and knowledge objects with indicating nouns. Don't make readers guess what to look for in the product. See Choose clarity over concision in this topic.
• Define all acronyms and initialisms at first use. See Acronyms.
• 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 ambiguous references between a pronoun and its antecedent. See Vague pronouns.

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 at first use 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 or if you can rephrase the sentence using simpler language.
• Refer to the Usage dictionary for examples of words and phrases that are unnecessarily complex and their alternatives. See the Usage dictionary.

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

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

Choose clarity over concision

Write in simple, concise sentences with a straightforward tone, and regardless of sentence length, always use indicating nouns to identify special elements or knowledge objects. Naming elements and objects removes ambiguity about what the element represents in the product and the instructions. Don't remove indicating nouns for the sake of brevity or to sound casual.

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

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