Splunk® Style Guide

Splunk Style Guide

The guidelines in the Splunk Style Guide establish best practices for writing technical documentation. Search docs.splunk.com to find documentation related to Splunk products.

Latest changes to the Splunk Style Guide

This table shows the history of updates to the Splunk Style Guide since its publication on December 2, 2019:

2024

Date Chapter or topic Change
June 12, 2024 Usage dictionary Clarified guidance around not using hyphens after the word "multi".
June 12, 2024 Usage dictionary Updated guidance for "drop-down".
May 20, 2024 UI text style guidelines Clarified places where error and warning messages can appear in a UI. Added examples for no data, permission, and configuration issues.
May 2, 2024 Capitalization, Colon, Dashes, Manual names, topic titles, and section headings, UI text style guidelines Clarified guidance around using colons in headers and the capitalization that follows.
April 17, 2024 Ellipses Added the topic with guidance on ellipses in documentation and UI text.
April 17, 2024 Usage dictionary Updated "directory" and added guidance for "folder".
April 15, 2024 Usage dictionary Added "admin" and "administrator".
March 5, 2024 Usage dictionary Added "synch".
March 1, 2024 Capitalization Added clarification to sentence-style capitalization on how to capitalize a phrase that starts with a number, such as a UI label.
February 22, 2024 Show symbols in text Determined that plus signs ( + ) in keyboard shortcuts pose no accessibility issue. Added keyboard shortcuts to the list of exceptions for spelling out symbols.
February 14, 2024 Formatting reference Updated guidance on formatting error messages to differentiate between inline and standalone examples.
February 12, 2024 Write unbiased documentation,

Write accessible documentation

Included guidance for writing about disability communities.
February 7, 2024 Usage dictionary Updated definitions for "toggle or toggle switch" and "switch or switch component".
February 7, 2024 Formatting reference Updated standard formatting for consistency and clarified ambiguous wording. Streamlined topic organization. Included new and up-to-date examples. Added cross-references to relevant style guide topics. Refined guidance for endpoints and methods.
February 5, 2024 Write accessible documentation Updated the Avoid directional language section to not reference color, shape, or pattern, and added more examples. Added a new section called "Combine color with other elements" with guidance for using color-based language in text.
January 24, 2024 Show symbols in text Added guidance for introducing symbols as nouns in sentences, added examples for avoiding symbols as abbreviations, and added exceptions for when it's okay to use symbols on their own without an introduction.
January 23, 2024 Splunk terminology and trademarks In the Splunk product terminology topic, removed superfluous information and included new sections on terminology categories and a basic reference. Across all topics in the chapter, refreshed examples and reorganized formatting to be consistent.
January 12, 2024 Voice and tone Added links to cross-references, added new examples and guidance, and reorganized content and examples formatting.
January 12, 2024 Best practices for including tables Restructured the "Don't" section so that all guidance is parallel in structure.
January 12, 2024 Avoid anthropomorphisms Expanded example section and added a new section on writing with commonly used anthropomorphisms.
January 11, 2024 Punctuation and symbols, Numbers Added links to cross-references, added missing nonbreaking spaces, and reorganized content and examples formatting.
January 4, 2024 Versions Updated organization of page. Included guidance around "higher" or "lower" language in reference to version numbers. Added new examples.
January 8, 2024 Write accessible documentation Added examples of how to refer to UI elements without relying on directional or visual language.

2023

Date Chapter or topic Change
December 18, 2023 Referring to third-party companies and products Added a section about using third-party terminologies.
December 11, 2023 Welcome to the Splunk Style Guide Added a section about the Splunk Style Guide for the Vale linter open-source ruleset.
December 8, 2023 Prepositions Added "into" as the preposition to use in the context of getting data into a Splunk product and "over" as another acceptable choice in other situations.
November 30, 2023 Best practices for including tables, Write accessible documentation Broke out the bullets of best practices into Do's and Don't's. Added guidance for making tables more accessible, including avoiding merged cells and special characters.
November 30, 2023 Usage dictionary Removed obsolete terms, consolidated terms, and added examples.
November 28, 2023 Where to look if the Splunk Style Guide doesn't answer your question Removed outdated writing resources. Added a book recommendation and 3 design system references.
November 28, 2023 Capitalization, Best practices for writing with lists, Bulleted lists, Numbered lists, Definition lists Reorganized topics and added examples.
November 21, 2023 Note callout boxes, Caution callout boxes Added examples.
November 14, 2023 Using prepositions in technical documentation Added the topic.
November 14, 2023 UI text style guidelines Added guidance for the written elements of a confirmation dialog box.
October 30, 2023 Diagrams
Updated example of a complex diagram and added guidance about surrounding text.
October 30, 2023 Including images in Splunk docs
Renamed the page and simplified sentences for easier scanning. Added more best practices for diagrams.
October 30, 2023 UI text style guidelines Restructured the Links section and updated the guidance for links to Splunk documentation to use descriptive labels instead of Learn more links.
October 23, 2023 Write unbiased documentation, Use device-agnostic language Restructured content and added examples.
October 6, 2023 Formatting reference Added formatting guidance for HTTP status codes.
Septermber 28, 2023 UI text style guidelines Added guidance for writing confirmation and success messages.
Septermber 6, 2023 Write unbiased documentation,

Usage dictionary

Updated the guidance to use "invalid characters" as the replacement term for "illegal characters", rather than "special characters".
August 17, 2023 Write accessible documentation Restructured content and added examples.
July 25, 2023 Usage dictionary Added "Splunk UI" to use only in reference to the product with the same name.
July 17, 2023 Splunk product terminology,

Usage dictionary

Updated guidance to never omit "Splunk" from Splunk Observability Cloud.
June 16, 2023 Formatting reference Updated formatting for REST API methods.
June 15, 2023 Write accessible documentation,

Best practices for writing with lists

Updated guidance on using lists instead of writing tasks in paragraph form.
June 15, 2023 Formatting reference Updated formatting for classes and methods.
June 8, 2023 Splunk product terminology,

Usage dictionary

Updated guidance about proper terminology for Splunk Observability Cloud.
May 31, 2023 Brackets,

Write accessible documentation

Updated guidance to use an appropriate word instead of the right-pointing angle bracket to describe menu paths.
May 24, 2023 UI text style guidelines Added section on symbols.
May 22, 2023 Manual names, topic titles, and section headings Added examples for naming scenario-based content.
May 19, 2023 Usage dictionary Added "after", "if", and "when".
May 19, 2023 UI text style guidelines Added examples of how to punctuate phrases and complete sentences to the "Terminal punctuation" section.
May 19, 2023 Using numbers in text Updated guidance to use numerals in most cases, even for numbers less than 10. Added examples of when and when not to spell out numbers.
May 2, 2023 UI text style guidelines Added new "Text formatting" section.
April 27, 2023 Keyboard shortcuts Added the topic.
April 12, 2023 Show symbols in text Added "right curly brace" and "left curly brace" as options for referring to the braces singularly.
April 11, 2023 Capitalization Added a section with capitalization guidelines for Splunk product names, features, and components. Also split out the information on not using capitalization for emphasis to its own section to make the content easier to find.
April 10, 2023 Splunk product terminology Added a "Splunk platform architecture components" section and reorganized the topic to make the information easier to find. Clarified that "Splunk platform" can be used without a definite article when it is a modifier.
April 5, 2023 Usage dictionary Added "premium apps".
April 3, 2023 UI text style guidelines Added the clarification that complete sentences take a period to the Terminal punctuation section.
March 24, 2023 UI text style guidelines Updated the guidance in the "Placeholder text" section to not use placeholder text.
February 24, 2023 UI text style guidelines Added "Field labels", "Help text", "Placeholder text", and "Empty state text" sections. Updated "Learn more links", "Tooltips", "Error or warning messages" and "Button labels" sections.
February 14, 2023 Write unbiased documentation,

Usage dictionary

Added guidance to avoid "disable" in documentation, and added entries for "disable" and "enable".
January 30, 2023 Formatting links in Splunk documentation Added a section called "Splunk product UIs" with guidance on how to format links from Splunk documentation to a Splunk product UI.
January 26, 2023 Usage dictionary,

Avoid directional language

Expanded guidance for using the words "above", "below", "earlier", "following", "later", "next", and "previous". Updated guidance on linking to sections when they immediately follow a sentence.
January 25, 2023 Ranges Updated guidance to advise using a suitable word, such as "to", "from", or "through", instead of a hyphen between ranges of numbers.
January 18, 2023 Show symbols in text,

Usage dictionary

Added "wildcard" as an option of what to call an asterisk to the table of symbols, and included the HTML entity code for nonbreaking spaces to the page. Added an entry for "wildcarded" to the Usage dictionary.
January 17, 2023 Usage dictionary Added an entry for ".conf". Updated the entries for "file name extensions" and "file types".

2022

Date Chapter or topic Change
December 19, 2022 Usage dictionary Added an entry for "upsert".
December 19, 2022 Measurements Added GHz to the table and alphabetized the list.
December 9, 2022 Usage dictionary Added an entry for "Experience".
November 30, 2022 A word about Splunk docs Added guidance to not include FAQs in Splunk documentation to the Goal-oriented section.
November 11, 2022 Referring to third-party companies and products Added topic with guidance on how to style third-party company names and products in docs and UI text.
November 10, 2022 Usage dictionary Added an entry for "leverage".
November 2, 2022 Usage dictionary Added entries for "abort", "bulletproof", "fatal", "hangs", "kill", and "suicide mode".
November 2, 2022 Write unbiased documentation Removed "hangs", "hit", and "suicide mode" from the table and moved the entries to the Usage dictionary. Added guidance that addresses terms and phrases that aren't inherently biased and biased terms that appear in third-party products.
October 17, 2022 Usage dictionary Added entries for "data", "datum", and "metadata".
October 7, 2022 UI text style guidelines Updated the example for "Page title" in the Capitalization section to more clearly demonstrate sentence-style capitalization.
October 7, 2022 Example names and domains Updated guidance about how to use just first names, shortened the list of first and second names, updated the list of names to be more gender neutral, and updated the list of example email addresses.
September 23, 2022 Manual names, topic titles, and section headings Updated the table of manual names examples from having before and after examples to correct examples only, with a description of what makes the name good.
September 22, 2022 UI text style guidelines Added examples of button labels and added guidance to avoid using articles in button labels.
September 12, 2022 Exclamation points Added guidance on when to use exclamation points and when not to use exclamation points.
August 26, 2022 Formatting reference Added intro text for linking to headers and subheaders in manuals. Updated an example.
August 23, 2022 Example names and domains Added http://www.buttercupgames.com as an acceptable example domain.
August 19, 2022 Usage dictionary Added entry for "hard-code, hard-coded, hard-coding".
August 10, 2022 Usage dictionary Added entry for "x (HTTP status codes)".
July 19, 2022 UI text style guidelines

Time

Added a new section called "Time" to the UI text style guidelines that contains abbreviations to use for units of time. Cross referenced this new section in the Time topic.
July 19, 2022 Apostrophe Added guidance on when to use apostrophes and when not to use apostrophes.
July 15, 2022 Usage dictionary Added an entry for "database".
June 22, 2022 A word about Splunk docs Added a section on timeless documentation.
May 25, 2022 Use device-agnostic language Added guidance around using device-agnostic language, such as "enter" and "select".
May 25, 2022 Usage dictionary Changed device- and input-specific terminology to be device- and input-agnostic, updating definitions for "click", "enter", "hit", "long press", "pinch", "press", "select", "select and hold", "spread", "tap", and "type". Updated a number of topics in the style guide to reflect updated usage.
May 6, 2022 UI text style guidelines Added a new "Button labels" section for guidance on writing button labels.
April 18, 2022 Formatting reference Updated examples for JSON bodies, REST requests and responses, and REST response body.
April 18, 2022 Usage dictionary Added an entry for "user base".
March 23, 2022 Usage dictionary

Use plain language

Added an entry for "needle-in-a-haystack" to the Usage dictionary and an example that shows a plain language alternative for "needle-in-a-haystack" to the Use plain language topic.
March 17, 2022 Documenting third-party products Removed Splunk Blogs as an option for documenting third-party information.
March 11, 2022 Usage dictionary Added entry for "stack".
March 1, 2022 UI text style guidelines Added new Links section with guidance on linking and expanded Learn more links section and Tooltips section.
February 28, 2022 Formatting reference Added developer text formatting elements and examples from Splunk Observability Cloud.
February 23, 2022 Manual names, topic titles, and section headings Added new section called "Name your topic in the TOC".
February 23, 2022 Splunk product terminology Removed outdated Cloud product suite content.
January 18, 2022 Show symbols in text Added table of what to call symbols in documentation. Deleted a page called "Special characters", which formerly held that information.
January 4, 2022 Write in indicative or imperative mood and American English spelling and phrases Updated phrasing from "standard English" to "American English".

2021

Date Chapter or topic Change
December 22, 2021 Phone numbers and Example names and domains Revised fictional phone number examples for Australia.
December 13, 2021 UI text style guidelines Updated capitalization guidelines to use sentence case for all UI text, including headings.
December 13, 2021 Capitalization Reorganized the content and made minor updates for clarity.
December 3, 2021 Example names and domains Updated information about fictitious IPv4 and IPv6 subnets and address ranges.
November 12, 2021 Formatting links in Splunk documentation Updated link to the Support and Resources page owned by the Splunk Customer Success.
November 3, 2021 Use plain language Added a section called "Choose clarity over concision" that describes how to use indicating nouns to identify knowledge objects and special elements.
November 1, 2021 A word about Splunk docs Added a bullet point under the "User-focused" section to not document the documentation. Added a bullet point under the "Goal-oriented" section to avoid documenting the UI.
November 1, 2021 Best practices for linking to third-party websites Renamed page from "Links to third-party websites" to "Best practices for linking to third-party websites". Updated example of an essential link.
November 1, 2021 Best practices for including links Consolidated bullet points about linking to Splunk documentation that used to be in "Formatting links in Splunk documentation" on this page.
November 1, 2021 Formatting links in Splunk documentation Changed name of page from "Links to Splunk materials" to "Formatting links in Splunk documentation". Reformatted the page into separate sections. Added code repositories. Deleted page called "Links to Splexicon entries and download files" and included the details on this page. Included examples of linking to third-party websites on the page. Updated broken links and added more examples.
October 27, 2021 Usage dictionary Updated entry for "out-of-the-box".
October 18, 2021 Usage dictionary Added entry for "wizard".
October 8, 2021 Including images in Splunk docs
Formatting links in Splunk documentation
Added information about when to use a video instead of a GIF and an example of how to link to a Splunk video.
October 8, 2021 Best practices for including videos Added topic.
October 7, 2021 Formatting reference Added formatting guidelines for Hexadecimal values.
October 7, 2021 Usage dictionary Added "hex".
October 1, 2021 Treat Splunk documentation as a recommendation Added topic.
September 27, 2021 Diagrams Added an example of a complex diagram.
August 30, 2021 Include alt text in images
Formatting reference

Formatting links in Splunk documentation
Best practices for linking to third-party websites
Definition lists
Using numbers in text
Manual names, topic titles, and section headings

Updated references of "Splunk Cloud" to "Splunk Cloud Platform".
August 23, 2021 Include alt text in images Clarified alt text guidance and added new examples.
August 11, 2021 Best practices for including tables Clarified guidance around formatting text in table cells.
August 6, 2021 Usage dictionary Added entry for "Splunk Cloud Platform". Updated references of "Splunk Cloud" to "Splunk Cloud Platform".
August 3, 2021 Usage dictionary Added "capability", "feature", and "functionality".
June 23, 2021 Usage dictionary Added "more".
June 11, 2021 Phone numbers and Example names and domains Revised fictional phone number examples for the US and Australia.
June 10, 2021 Usage dictionary Added "read-only".
June 8, 2021 Write unbiased documentation Removed a line in the table that says to avoid "Native".
June 7, 2021 Usage dictionary Added "Premium Solutions".
June 4, 2021 Usage dictionary Added "n/a".
June 3, 2021 Numbered lists Added guidance for marking substeps in a numbered list.
May 26, 2021 Splunk product terminology Added a new section with usage guidelines for cloud-only product suites. Updated "Splunk Cloud" to "Splunk Cloud Platform".
May 25, 2021 Manual names, topic titles, and section headings Added guidance about numbers in titles and headings.
May 25, 2021 Using numbers in text Changed name from "Numbers or numerals?" to "Using numbers in text". Added guidance and examples for hyphenated numbers, ordinal numbers, and numbers in headings, along with organizational changes to the page.
May 25, 2021 Quotation marks Added sections about logical quotation, straight quotes, and single quotes in code examples.
May 6, 2021 Include alt text in images Added and clarified guidance for including alt text.
April 28, 2021 Usage dictionary Added "dark mode", "dark theme", "light mode", and "light theme".
April 27, 2021 Including images in Splunk docs

Screenshots
Write accessible documentation

Added guidance about screenshots needing to be in the UI light theme with the screen zoomed to 100%.
April 23, 2021 Usage dictionary Added "cog", "gear", "fail over", and "failover".
April 22, 2021 Usage dictionary Added "standalone".
April 21, 2021 Usage dictionary Added more incorrect examples to "log in" and "login".
April 7, 2021 Measurements Added "kibibyte".
April 1, 2021 Usage dictionary Added "Boolean".
March 17, 2021 Usage dictionary Added "JSON".
March 17, 2021 Usage dictionary Added "query" and updated the "search" entry.
March 17, 2021 Formatting links in Splunk documentation Added a table row on linking to configuration file topics.
February 22, 2021 Write unbiased documentation Added a topic about writing unbiased and inclusive documentation.
February 17, 2021 Include alt text in images Renamed the "Include alt text" topic to "Include alt text in images".
February 17, 2021 Write accessible documentation Renamed the "Write docs for everyone" topic to "Write accessible documentation".
February 10, 2021 Example names and domains Added additional names for greater diversity.
January 5, 2021 UI text style guidelines Added a "Numbers" section with guidance to use numerals in UI text.

2020

Date Chapter or topic Change
December 3, 2020 Usage dictionary Added "multifactor authentication".
December 3, 2020 Formatting links in Splunk documentation Updated guidance about linking to subheadings. Now okay to link to an H2 or H3, and treat it the same way as linking to a topic.
November 30, 2020 Formatting reference Changed name of page to "Formatting reference". Added explicit guidance for all elements in documentation rather than generalizations. Added more examples and some sidebar comments.
November 30, 2020 Formatting text chapter Deleted the "Bold", "Italics", and "Monospaced font" topics from chapter.
November 30, 2020 Best practices for linking to third-party websites Clarified the difference between essential and supplemental links. Added new guidance about linking to essential sites.
November 30, 2020 Usage dictionary Updated formatting in "File paths". Removed guidance that says not to use directional language in UI text.
November 30, 2020 Titles and headings chapter Clarified guidance around how to use heading and text together in "The order of headings" and "Headings and text together" sections.
November 18, 2020 Possessive pronouns Added guidance to avoid possessive pronouns in UI text.
November 13, 2020 Usage dictionary Added "SSH", "URI, URL", and "URN".
November 13, 2020 Measurements Added tebibyte (TiB).
November 12, 2020 Titles and headings chapter Deleted topics on writing tasks, prerequisites, supertasks, next step sections, and see also sections. Changed "Content structure" chapter name to "Titles and headings".
November 11, 2020 Formatting reference Added formatting guidance for URIs and URLs.
November 9, 2020 Usage dictionary Update definitions for "ad hoc", "drilldown", and "lookup". Added "app". Added examples to "command-line" and "real-time".
July 22, 2020 Usage dictionary Updated "master" and "install". Added "slave" and "deploy".
July 20, 2020 Usage dictionary Updated "blacklist" and "whitelist".
May 26, 2020 Usage dictionary Added "AM" and "PM".
May 22, 2020 Usage dictionary Clarified guidance for "*nix*, "Linux", and "UNIX".
May 22, 2020 Usage dictionary Added "blacklist" and "whitelist".
April 13, 2020 Usage dictionary Added "into". Also added a correct usage example to the Manual names, topic titles, and section headings topic.
April 13, 2020 Usage dictionary Added "reenable" and revised the entry for "reenter".
March 24, 2020 Usage dictionary Clarified "multivalue field". Updated "plugin" as a noun or adjective.
March 19, 2020 Example names and domains Updated IP address blocks to be ranges.
March 9, 2020 Numbers or numerals?

Time

Added guidance around duration of time.
March 5, 2020 Write in indicative or imperative mood Updated title and guidance to emphasize writing in indicative and imperative mood and to avoid writing in subjunctive mood. Added new examples.
February 19, 2020 Usage dictionary Added "spin up, spin down".
February 18, 2020 Formatting reference

Brackets

Clarified language and examples for square brackets around .conf file stanza names.
February 5, 2020 Usage dictionary Added "directory".
January 31, 2020 Usage dictionary Added "drilldown" as an adjective.

2019

Date Chapter or topic Change
December 23, 2019 Usage dictionary Added "tarball".
December 12, 2019 Commas and decimals Added clarification to use standard American-style formatting for commas and decimal points in numbers.
Last modified on 14 June, 2024
Welcome to the Splunk Style Guide   A word about Splunk docs

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


Was this topic useful?







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