Splunk® Style Guide

Splunk Style Guide

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

Use plain language

Using plain language helps the widest variety of users understand what you write. Remember that Splunk 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 Splexicon 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.
Last modified on 12 December, 2019
PREVIOUS
Tone
  NEXT
Be active and present

This documentation applies to the following versions of Splunk® Style Guide: current, current


Was this documentation topic helpful?

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters