Technical Onboarding information category

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.

11 thoughts on “Technical Onboarding information category

  1. Pingback: Rachel Quickblogge
  2. I mean, you should read The Phoenix Project if you haven’t yet, but I’m not sure how much it brings to this specific topic.

    Did you ever do Write The Docs? Sadly, it just passed this year, but I found it to be a pretty good conference when I went some years ago. This would be a good talk topic for next year there.

    I have some thoughts on the value of programmers and the kinds of activities they should be performing, but I’m having a hard time phrasing them. We should talk sometime.

    • Hey Bart, so great to hear from you! Yeah I actually recently read The Phoenix Project about a year ago! Really changed my thinking on value streams and how the hard part is still people, but we can make it better with buy in and proven process!

      I went to WTD once in, I think, 2014? It was great, and you’re right, this IS kinda a talk for that conf!

      Let’s get a beer soon 🍻

  3. For years, a key part for me for onboarding new folks is to talk about our organization’s weird and wacky processes and terminology. “If you’re getting confused, that’s a good thing. It’s more confusing than it should be.”

    A lot of that “undocumented” stuff is often terminology and unfortunately often, subtle bits of process (“of course we use this branching strategy!”).

    The question I ask myself is “what’s weird about what we’re up to?” Everytime I bring someone on board, we find new weird things. Less frequently than I would like, I document them. Getting new folks to document some amount of the weirdness can be a great way to help them get their heads around stuff.

    • I think it’s so murky what’s undocumented and what needs to just be LEARNED! But yeah it’s also definitely all about constant checking in and “hey would you please note anything that seems awful or even unexpected so we can talk about it and make it better”

  4. Pingback: Rachel Quickblogge
  5. Agreed about the importance of acknowledging undocumented stuff!

    One trick I’ve leveraged to help make this better is to make the onboarding engineer’s first set of responsibilities around updating the onboarding docs & process for the next person as they onboard. This helps me keep track of where they are in the process, gives them a quick and very achievable goal where I can see them execute on some low-pressure clearly-defined work early, and also helps catch “gotchas” that are easy for the team to work around but are NOT obvious to outsiders.

    • Hey Eric! Thanks so much for reading this! I kinda dislike the “ok now YOU fix our bad process,” which I know is a bit of a misrepresentation of what you said. But I would just really love it, while taking feedback and all of course from the person who is onboarding, if we had this stuff quite a lot more worked out before the new person was thrown onto it! That said, there’s no eyes like fresh eyes for process docs. It also isn’t useful sometimes, and it’s hard to communicate that sometimes more context is needed and it’s not going to tell you how to do every exact thing! So… I don’t really disagree!

      • Hiya!! It was a great blog post!!! I should have led with that!

        I agree about offloading process onto the new person…..


        What about a middle ground? Onboarding buddy is responsible for process updates. But new person gets to observe and report. Together they produce a doc, which the _onboarding buddy_ has to action on to actually make the changes.

        Would that feel better?

      • Hiya!! It was a great blog post!!! I should have led with that!

        I agree about offloading process onto the new person…..


        What about a middle ground? Onboarding buddy is responsible for process updates. But new person gets to observe and report. Together they produce a doc, which the _onboarding buddy_ has to action on to actually make the changes.

        Would that feel better?

        (also thank you for that feedback…I hadn’t considered that angle and yeah, I can see where it would not feel good)

Leave a Reply to Eric Shamow Cancel reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s