Hey folks, been a while on the main blog. Got lots of stuff I’d like to talk about here at some point (like getting off twitter via buying another WP blog)! The one for today is borne of some work onboarding I’m doing for a new person on the other side of the world from me, which brings endless fascinating challenges, basically all of them good!! Was talking with my PyLadies besties (six of us ran the portland pyladies chapter for a few years and we have all stayed close) and we got to some interesting places as far as technical (and possibly other kinds that I can’t speak to) onboarding.

As I see it, there are four categories of information relevant to a new engineer*.

1. What I expect you to bring to this role
2. What I expect you to absorb and internalize *without* documentation
3. What I expect you to read and reference from documented internal sources
4. What is undocumented but which should be documented.

You’ll notice that three of these are pretty straightforward. Or at least, ideally they would be. Regarding item 1, what I expect you to bring to this role should be clearly laid out in the job req, and in our case in Data Center Provisioning, we wanted them to have strong networking, decent general command line ability (this can be switch-specific though – switches, like Cisco network switches and Arista network switches, and others, have their own structure that is NOT filesystem tree based, but which is somewhat cross applicable to ~Linux command line interfaces, which is my familiarity), virtualization experience, a little scripting, and if you have cloud ops experience and some programming, that’s a bonus.

Re the third (we’ll come back to the second), what I expect you to read and reference from documented internal sources is never as grand as you want it to be! It isn’t that we don’t have a ton of docs – we do, but as anyone in this field knows, it is a monumental task to keep it updated and constantly added to in relevant, searchable ways. We do our best and are always trying to come up with ways to incorporate this work into a regular cadence of attention and discussion.

Which brings me to our fourth category, what’s not documented but should be. This is a huge category, and it’s absolutely fuzzy with the second category! There is so much that I can CLEARLY state that should be documented, though, so even though there is gray area, there is such a huge quantity that is utterly black and white.

Finally, the category of what I expect you learn and internalize *without* documentation. I bristled at the idea of this earlier on in my career. Now, I am pretty sure that this is the secret sauce of any technical role, maybe any role period, and I believe that my success as a colleague-trainer depends upon clarifying this category over all others. The clearest examples of things in this category are, like, (in my field anyway) how to use code repositories, including how to submit your code for review and how to generally use a cloud remote tool like Github (that’s probably a pretty odd label for what GH is.. please forgive it). These are the kinds of things you would explicitly show a junior level person, or someone whose background is ENTIRELY networking or physical racking-and-stacking in datacenters, but at my job we generally expect that you have this.

The less clear pieces are harder to describe (no kidding lol). I think this is ultimately the category of company/job specific knowledge, that as you deepen your understanding, hopefully gives you tools and knowledge for future career as well. Some of this is historical context for your job, that you don’t really get until you’ve been there for a minute. The context that I have, having been at Fastly for 18mo now (not a long time but more than a flash in the pan), is a key part of the value that I bring, and the longer I’m in this job, the more valuable that will be (but not necessarily – there is an upper limit that is probably worth exploring in a “should you move on from your job” kind of post). Another piece might be, at least in my case, the unique design of what we build. Not going to get too specific in a public blog post of course, and while you can learn design generalities for what we do and make and provide, the specifics of our builds will not be known until you develop some working, repetitive knowledge. And then it will change subtly, over and over and over!

“But wait, Rachel, shouldn’t this stuff be documented?” This question is basically THE reason I felt the need to write this blog post. The answer to some of it is yes! The answer to a LOT of it is, “uh… kinda?” Like, yes, we have design docs, which are thoughtfully created and introduced to the relevant teams! And they apply to one version of it, or maybe one category of versions of it. But this one is different for pretty good reasons, and you can tell by looking at X and Y. And this other one is different for reasons we later discovered aren’t very good, and you can kiiiinda tell by looking at Z or W! I hope this is not too abstract. I’d like to get to a place where I can really define this category.

I think this second category is also partially the reflection of the fact that we simply cannot document everything. It’s not possible, and further, we got work to do folks! One of the common personal aphorisms I return to is that they’ve hired us here for our brains. This, and my last job, are not widget jobs, like my support engineer job from 2014-2016, which was extremely technical and demanding, but which 90% depended on a) ticket inflow and b) having TOO MUCH ticket inflow in order to never “overstaff” in this “loss-leader” department (a characterization I find short-sighted and even cruel – can you tell my feelings on this with what I’m putting in scare-quotes??). They need us to be finding and solving the continual edge-cases we encounter before they become major incidents or otherwise impede the function of our organization… and we are very lucky to be able to do that. Sometimes we’ll all gripe about some bizarre complexity or a decision handed down to us from a few levels up, but really, we’re all just trying to solve technical AND business problems, and it’s genuinely a rare and special thing to be given the freedom and the salary to do so with as much of your brain as you care to engage.

Quick side bar, I do think that a very technical job (to a point!! no ocean-boiling, that’s burnout territory) where you really are trying to solve problems and get shit done a little better each time, is rather a fountain of youth. Keep your brain sharp and you keep dementia at bay a bit better! No guarantees in this world of ours but cognitive function is a real thing that declines and like any muscle, the way to keep it going is to USE it!

So. Getting back to the categories of onboarding information… What do we do with this? Well, I’m working with it as we speak, and it’s HARD! It’s a bit know-it-when-I-see-it, and part of trying to write all this out was to personally try to be able to recognize the “second category” of information a little faster, so I can impart it better, so our newest engineer can internalize it more easily, so we don’t fall into the trap of trying to document something like “and then, type cd foldername…..”. And of course, the point of it all is to prepare our newest engineers on our team in the best possible way we can for themselves and for our organization!

Truly I’d LOVE to hear what you think about these categories, and if this reminds you of Some Book (or blog post!) I Should Read, please let me know!

* this isn't the place to discuss coder/programmer/sysadmin/noc/etc all having the title of engineer, it's fine, your opinion probably isn't wrong even if we don't agree, just not going to talk about it here.