An Inside Look at the Life of a Technical Writer at Grafana Labs
People think technical writing is boring, but sometimes documenting software is an adventure.
It’s not an adventure like “whee, got my sword and shield, adventure time!” No, it’s more like taking a nice stroll down a path to an unfamiliar-but-known destination when the ground suddenly opens up under your feet. As you’re falling down into the depths, that’s when you realize you are about to have an adventure.
I’m a technical writer at Grafana Labs. Writing, editing, and generally improving the technical documentation is what I do for a living. (Writing snarky blog posts is a fun hobby, though.)
So there I was, testing Grafana installation documentation on my Windows machine and Linux VMs. Before moving on to the next task, I decided to do a nice, simple task on both machines. Something quintessentially Grafana; something so simple that nothing could possibly go wrong.
Word of advice: Never say that. Not even in the privacy of your own head.
I decided to install a plugin.
No problem on Linux.
Windows, though…
Error: ✗ Failed to extract plugin archive: Could not create ../data/plugins/sidewinder-datasource. Permission denied. Make sure you have write access to plugindir“No problem,” I thought. “Maybe it needs to be run in PowerShell.”
Same result.
I glared at my computer, then remembered that running PowerShell as an Administrator was a thing. It didn’t take long to figure out how to do that on Windows 10. And thankfully, it worked.
While I waited for the installation to finish, I had a stern discussion with my laptop. “You only have one user: me. By definition, I am the administrator. That means everything I run on you is being run by an administrator. I own you!”
The computer reacted about as one would expect.
Installation complete
I breathed a sigh of relief and entered the command Grafana CLI printed at the end: service grafana-server restart.
Response:
.\service : The term '.\service' is not recognized as the name of a cmdlet, function, script file, or operable
program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.
At line:1 char:1
+ .\service grafana-server restartAfter a few questions to my developer colleagues, I found out this was a Linux command, and I needed to enter a different command for Windows. That will be hopefully corrected in Grafana 6.7 issue #20983.
The whole “PowerShell as Admin” requirement seemed like a pretty big gap in our documentation so, busy documentarian that I am, I decided to add a few paragraphs to address it.
I opened Install Plugins and was greeted with a whole list of Grafana CLI plugins commands.
Oh, hell no.
For those of you who are unfamiliar with topic types, we technical communicators try to divide content into concept, task, and reference topics. This was a big chunk of reference content in what should have been a task topic.
“No problem,” I thought. “I’ll just copy and paste that content into Grafana CLI where it belongs and write an actual task for installing plugins.”
I moved the content and then ran grafana-cli --help to make sure nothing had changed since the Grafana CLI had last been updated.
Amid the wall of text listing all the options, commands, and other useful things to know, there was one glaring surprise.
“What do you mean Global Options?”
Global Options–and several other commands listed in the Grafana CLI help output–weren’t even documented.
Now, I could have moved back to the plugins docs, but that sort of documentation gap is like an itch. Once you know it’s there, it bugs you. Haunts you.
I couldn’t just move on. There was nothing to be done but to venture into the bowels of Grafana CLI and tap into developer brains to slay the beast.
Long story short (or as short as I can manage at this point) PR #21179 applied all the updates.
I hope you enjoyed this little glimpse into the Land of Software Documentation. Let us know if you have any suggestions for parts of the documentation that I should tackle. I’m always up for another adventure!
