What We Can Learn From The Splunk Technical Writing Team
I used to be in the class, but unfortunately I Splunked out
I listened to the Splunk Podcast and heard them interview Christopher Gales — he currently heads the Splunk Documentation Team, and one thing he described is how Splunk, in contrast to many other companies, opens up their documentation to the public. By this, I mean that anyone on any page can make a comment or suggest an edit, and the technical writer who owns the Splunk page will usually respond promptly.
I actually tested this a while ago. A really popular Splunk document had the word “are” repeated twice for no reason. I left a comment, and the document was fixed within about 24 hours.
This week I tested it again. A document said, “By using a separate browser tab, you will keep this open this tab with the Search Tutorial instructions. You can switch back and forth between the browser tabs.” I corrected it to “By using a separate browser tab, you will keep this tab open with the Search Tutorial instructions.”
This is pretty low-hanging fruit, but I have a plan. By targeting easy things like this, I will systematically determine what technical writers maintain what Splunk documentation. Sooner or later, one of those is going to be Sonnet. At that point, I can do whatever I can to submit non-trivial contributions.
Then, and only then, I will ask her for a free T-shirt. My eye is on “Counter Errorism.”
Splunk Believes In Having Technical Writers Interact Directly With The Customer
In Christopher Gales’ book, The Product Is Docs, he advocates for having technical writers who work closely with the customer. You can see evidence of this in various Splunk forums — when users ask questions, a technical writer may be the first to respond with a fix.
Unlike some resources, Splunk formats their documentation much like a Wikipedia page. It changes rapidly, it welcomes new contributors, and it adapts as needs change.
Above is a snippet from their Search documentation — several years ago, a Splunk technical writer from IBM made an effort to reformat many of these pages, so that all of them included example commands and adhered to a certain format. This is something that, interestingly, many technical resources lack. They go to the trouble of describing how a command works in an abstract way, yet they don’t bother to include a few sentences for an example.
geostats was a critical command when we last messed around with the Twitter Splunk App, but I have not been able to resurrect this. Possibly because of changes to the Twitter API, this Splunk app no longer seems to work out of the box at all.
Splunk Embeds Its Writers Into The Development Process
They use agile. They size stories the way a software engineer team would. In the book, they lay out two approaches: Having writers directly place themselves in team, like full-on members, or have writers work separately but still follow sprints. In either case, they are still using the rapid development model characteristic of agile.
Splunk Believes In Diversity
They hire technical writers from artistic backgrounds, software backgrounds…even a musician and an astronomer. Gales himself came from something of a software background in the early days. His experience with SQL may have been reminiscent of the Splunk Processing Language and its queries, but that is just speculation.
One thing that disappointed me about The Product Is Docs is that it simply attributes everything to Gales and “the documentation team.” Knowing them, every team member probably had ownership over some book section. It would have been nice to actually see the other technical writers listed with attribution.
Technical writing is basically teaching. It represents a kind of middle ground between the grammatically strict world of programming and an art like blogging, in which I have full creative control and can freely jump paragraphs unnecessarily, string together seemingly random ideas, or close with a link of Gatsby The Corgi visiting San Francisco.
Your mileage may vary.