We all love documentation. Documentation is important! We understand the things we should document. Implement a configuration flag, document it. Architect some new infrastructure, document it. Find an operational risk in your company, document it.
Reading good documentation, and using it to get yourself out of the hole is excellent, and I always go to the docs as my first port of call when solving some technical problem. The duality of man does however require that I suck at documenting things.
I suck at documenting things, I think, because I regularly assume that everyone considers the problem similarly to me. I fail to realise that the singularity has not yet taken hold of the nerd race, and assimilation is yet to come. Therefore the need to document my own work is not inherently apparent at the time of implementation. Egotistical, sure. Common? Absolutely.
My experience in dealing with a lot of software in my career, from various vendors, tells me that this is not a unique issue. Documentation quality varies wildly, and coverage more so. Often companies lack an understanding of their target audience, and make assumptions about the expertise of the people charged with ‘just getting solution x off the ground’. I will not point and shame, but there are big players in this category that require you to have studied Data Science to at least Masters. Preferably alongside a reading and comprehension rate of over 800 words per minute, if you want to get the docs read today.
Coverage is potentially an even larger issue. If some functionality is covered by your software’s API, it really needs to be documented comprehensively. With context. And pretty pictures if necessary. Please.
So we’ve established that I have a penchant for ‘good’ documentation, that I suck at writing it, and that there’s a lot of poor documentation around. So what?
That’s the end of the story, as far as ‘working it out on your own’ goes. There are of course ‘other people.’
“The ‘overflows!” I hear you cry. Or perhaps “Professional services!”. Ah yes, dear reader, but what of ‘time’ and ‘money’? I have engaged with fantastic paid professional services providers, like Percona and Elastic. They do exactly what you ask of them, and by and large explain the solutions to your problem coherently. But! Engagement takes time, and money. Stack’ may not have the answer. You may not be asking the right questions. Scoping your company’s requirements for professional services might take several meetings over several weeks, and my configuration doesn’t work right now.
Let’s dream up an illustrative example. I found a flag in a configuration file, and there’s no documentation referencing it anywhere. Big brother’s got nothing. The GPTs stare back, blankly. The flag doesn’t even have a relevant default, by way of example – an empty string. Its name is woolly, unspecific. But intuition says ‘I bet that flag would help fix my problem.’
You have a few “free” options once you have exhausted the hive mind, of course. The first being to try and change it. See what happens. “It’s a production system”, you say. Well ok, how about staging? Who has staging for an installed service, sitting around doing nothing, for months at a time? Well, some people. Sure. And good for them, I’m very happy if not a little bitter. What about us mere mortals?
Open Source software has yet another benefit to be espoused, then. Even if the docs don’t see you right, there’s always the code. It’s right there. A search in the repo here, a look for a definition there, find reference in a couple of if statements… And we know what it’s for. We likely also know the expected type of that flag, other options, and, if the code is well commented, the developer’s thoughts on its wishy-washy name.
This approach has seen me right too often to recount instances individually (and without incriminating some poor Open Source software vendor for less than optimal documentation.) This is the reason engineers (choose a flavour, infrastructure engineers, system administrators, DevOps engineers, SRE’s) should all have a smattering of knowledge around a language or two. Must have, in my not-so-humble opinion, to become ‘senior’. I don’t believe for a moment we should all be software devs, but understanding basic constructs and principles when implementing Open Source solutions can get you so far. I can’t write GoLang, or Rust, but understand enough of other languages guiding semantics and primitives to be able to read my way through the code (with the help of a good search engine.) Unless it’s lisp, of course. Then we’re in the wilderness.
Documentation is important, read the source.
