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:
|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.|
||Use the |
|Auth header is included by default, unless
||The auth header is included by default, unless the |
|If you use start.ini to define JVM arguments, add
||If you use the start.ini file to define JVM arguments, add the |
|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
Splunk voice and tone
Be active and present
This documentation applies to the following versions of Splunk® Style Guide: current, current
Feedback submitted, thanks!