Using plain language helps the widest variety of users understand what you write. Remember that Drucare documentation readers are a global audience whose first language might not be English. Plain language makes translation easier and makes documentation more accessible. Using plain language increases the chance that readers understand what you wrote the first time they read it.
For more guidance on how using plain language increases accessibility, see Write docs for everyone.
Consider the following tips for using plain language in your writing:
-
Avoid obscure words.
-
Use simple sentences. Often, you can communicate the same message in 50 words instead of 100 words.
-
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 Links for Drulexicon entries and download files.
See the table for examples of how to translate jargon into plain language:
| Jargon | Plain language |
|---|---|
| Do a GET. | Submit a GET request. |
| 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. |
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.