Splunk voice and tone

The way you speak and the way you write is likely very different. The way you talk is probably verbose and colloquial whether you intend it to be or not. Traditional technical writing tends to be dry and formal. Splunk documentation finds a balance between the two: Splunk docs are casual and approachable, yet succinct and direct.

When you create written content, shape your docs around your reader's needs and expectations, and write to them as though they are a professional acquaintance. Aim to be confident, friendly, and comprehensive, and not insensitive, saccharine, or complicated.

Here are a few guidelines you can follow to achieve a balanced tone in your writing:

• Stay away from jargon or idioms. See Use plain language.
• Write in active voice and present tense whenever possible. See Be active and present.
• Use contractions, such as isn't, don't, and can't. See Contractions.
• Write precisely and concretely.
• Avoid qualitative language, such as calling things easy or simple. What's easy for one user might be challenging for another.

Examples

The following table shows examples of writing that are too formal, too casual, and just right:

Too formal	Too casual	Just right
Note that Splunk Enterprise Security automatically enables SSL; therefore, confirm that the protocol in your web browser is "https" (for example: https://splunkserver:8000).	ES enables SSL, so you might want to make sure that your web browser is using HTTPS, like in https://splunkserver:8000.	Splunk Enterprise Security enables SSL. Check that the web browser protocol uses HTTPS. For example, https://splunkserver:8000.
Please select the Complete button to complete the process and display the result.	When you select Complete and you see the result, you know you are done. Way to go!	Select Complete.
The information about the KV store status can be retrieved from the kvstore/status endpoint via the GET method.	Do a GET on the kvstore/status endpoint.	Submit a GET request to the kvstore/status endpoint to access KV store status information.
Forwarder management is a graphical user interface (GUI) that is built on top of the deployment server and offers a streamlined solution to configure the deployment server and monitor the status of deployment updates.	The forwarder management GUI lives on top of the deployment server. The GUI makes it easy to configure your server while monitoring any updates that might come up.	You can configure the deployment server and monitor the status of deployment updates with the forwarder management graphical interface.
Metrics can be used for the investigation, monitoring, and troubleshooting of your pipeline in real time.	You can use metrics to do some really cool things like look into, keep an eye on, and tweak your pipeline as the data is coming in.	Use metrics to investigate, monitor, and troubleshoot your pipeline in real time.
A gauge is a metric that is composed of a single numerical value that can arbitrarily increase or decrease depending upon the value of which the metric is tracking.	A gauge is a number that can go up and down for a couple of reasons, like if it gets hotter or colder in a server room.	A gauge represents a single numerical value that changes based on what you're tracking.