Splunk documentation feedback: how it works and what makes a champion
On Monday this week, we at Splunk HQ had the pleasure of hosting Rich Mahlerwein, founding SplunkTrust member, cape-and-fez wearer, and Senior Systems Engineer at the Forest County Potawatomi IT Department. During his visit, I asked Rich to come and meet the documentation team.
Rich is legendary among the Splunk doc writers for the quality of the feedback he offers, and how often he sends it. So they were eager to meet him in person.
Here on the Splunk documentation team, our writers work hard to make sure our content is relevant, accurate, and matches the way our customers use Splunk software in the real world. An essential aspect of that is customer feedback. The Splunk doc team enjoys a constant, ongoing conversation with our customers. We email or talk with over 40 customers a week. I often describe that continual contact as “the fuel in our engine.” If you have ever submitted feedback on Splunk documentation, you know that we always follow up. Your comments and suggestions help make our documentation great and ensure that we are giving you the information you need to be successful and confident when you use Splunk software.
The feedback form at the bottom of every topic gives you two ways to contact us: Was this topic useful? and Post a comment. Most customers choose the default Was this topic useful? option, which emails the doc team directly. If you choose Post a comment, it will post a visible comment on the topic itself, and we will respond there.
The steady stream of doc feedback email provides our greatest opportunity to work directly with you on the issue you found. Here are two quick tips that will help us follow up:
- Submit your feedback when you are logged in to splunk.com, or include your email address so we can reach you.
- Use the YES or NO option to tell us if the topic was useful, and then tell us why. Be specific. If you take the extra few minutes to give us this information, we are in a much better position to make the improvements you want to see.
Here is an example of doc feedback that we can’t do much with, because we have no contact information and no sense of the issue the customer was struggling with.
User: 63.XX.XXX.XX Email: Result: NO URL: http://docs.splunk.com/Documentation/Splunk/6.4.2/Admin/Specifyaproxyserver Additional comments:
Let’s get back to Rich. What does his feedback look like? Here’s a recent example.
User: 199.XX.XX.XXX Email: rich.... Result: YES URL: http://docs.splunk.com/Documentation/Splunk/6.3.5/Data/MonitorWindowsprinterinformation Additional comments: I feel the "Fields for Windows print monitoring data" should be more fleshed out. I enabled an input for this for my printer guy, and we've noticed a few things that I think this document ought to explain. For instance, for each job we get two events - "operation=set" and "operation=add". I think perhaps the latter is it adding the job to the queue and the set is something else, perhaps the actual printing start itself? I suspect this information is the same for nearly all recent versions of Windows, and there's only 18 fields I think, so perhaps listing those fields and what they mean could be useful. I can send in a dozen events if you want, just won't do it here because the text box thingy I'm typing in eats formatting. Also up nearer the top it says "The printer monitor input runs as a process called splunk-winprintmon.exe. This process runs once for every input you define, at the interval specified in the input. You can configure printer subsystem monitoring using Splunk Web or inputs.conf" That's great, but is there any more information on exactly what it's grabbing? From *where* does the winprintmon get its information? It wouldn't be important except it's reporting slightly different stuff than windows does and knowing where its getting its info would help. Oh, and one more thing? Why not, perhaps as an additional possibility, set up the windows Event logs Microsoft-Windows-PrintService/Operational and pull off the Event ID 307? Those seem to have a fairly compact and full set of information: all the "usual" windows event log fields like user (FILLED OUT FOR ONCE YAY WINDOWS!) and computer, then text that looks very parseable: "Document 81, Print Document owned by colette.dehart on PRO-SCN-02 was printed on PRO-BLK-01 through port 10.138.0.45. Size in bytes: 126832. Pages printed: 1. No user action is required." Just a thought.
A message like that enables us to contact the submitter immediately, have a meaningful conversation, and improve the docs right away.
So far this year, Rich has submitted 19 exemplary feedback emails like this one, plus an uncounted number of informal comments and suggestions through the splunk-usergroups Slack channel. There isn’t a month that goes by where we don’t hear from Rich two or three times, with specific, detailed, thorough suggestions and questions that enable the writers to focus their efforts on improving our content for all customers. In this way–as in so many others–Rich is a champion Splunk community member, making sure to apply what he knows about Splunk software so that it benefits everyone else. And when he submits feedback, his characteristic sense of humor is always on full display.
We marked the occasion of Rich’s visit to HQ by presenting him with a “splunk > docs feedback champion” trophy, in front of the entire Splunk doc team. Here’s a picture of Rich with his award.
And here he is with as many doc team members as we could cram in around him.
If you bump into Rich at .conf 2016 in Orlando, ask him about it!