Writing Docs with Style: The Splunk Style Guide

I'm excited to announce that, after years of internal development and hands-on use, the Splunk Documentation team published its Splunk Style Guide today. With this guide, customers, partners, and documentarians in companies worldwide can follow, apply, and adapt the same guidance we use to write Splunk documentation.

Good technical writing helps readers sort through complicated information, accomplish a task, and achieve their goals. But writing is hard. Writing good technical documentation is harder. And having a team of writers write great technical documentation with any level of consistency is hardest of all. 

Style guides are the main reference that help writers achieve consistency across a doc set. Instead of hemming or hawing over capitalization, commas, or contractions, a style guide puts guardrails in place so writers can spend their time increasing their product knowledge and writing for an audience that’s eager to learn.

And now we're sharing the guidance that’s shaped Splunk documentation into industry-leading documentation with the whole world: the Splunk Style Guide.

The newly published Splunk Style Guide covers myriad topics:

  • Achieving the ideal Splunky tone
  • Clarifying product terminology
  • Creating documentation that’s accessible for everyone
  • Using punctuation, numbers, and capitalizations consistently

And there’s more! The Splunk Style Guide doesn’t just cover writing style—it has a dictionary of terms to use and avoid, is replete with best practices in good information design, and offers suggestions on formatting text elements when you have only a handful of special formatting options to choose from.

The Splunk Style Guide is our one-stop shop for defining the elements that create a consistent voice, tone, and writing style across our wide-ranging documentation. Our technical writers use it to craft their docs, and we hope you’ll find it useful as you create your content, too.

Alyssa Yell

Posted by