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
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.