5 ms·

When you hire new people and they encounter this over and over again, onboarding drags on so, so much longer than it should, because people taking your position

• Frost1x 3y ago
  The issue often more has to do with how others interpret simply. Someone working in some code base who has some arcane undocumented process and structure to get something functioning or has developed some abstraction over the years may, relative to themselves, think the specific task is "simple." They've lost context of the actual full process and set of abstractions for someone else because they've been so immersed in that space. For most people working with someone like this directly, that's fine and dandy. I know the process isn't actually simply, I know there's a lack of information, and I know there's a significant hidden time component for someone else to step into that space either if it's me handwaving away complexity or if I'm being handed something that handwaves it away. The real issue here is that opinions of those people don't matter in terms of the interpretation of complexity. It's the bystanders who don't care about any of the technical pieces. They just want Alice to take over where Bob left off and move on to get the functionality they're paying to get. Bob can gaslight Alice that it simple all day and Alice isn't naive, she knows better. But business manager Carson is unaware of this and also doesn't care, at all, and when Bob says it's simple while Alice is struggling and Carson starts pressuring Alice like she's an idiot or incapable and Bob steps in and does said task quickly, it looks bad on Alice. If Carson is a good technical leader or manager, they know what's actually going on and Alice may not be incompetent, Bob just has poor documentation or has lost touch with reality. Carson is rarely a good technical manager and has others pressuring them, so you're left with how "simple" something is looking bad on Alice in almost all cases. This is why developers hate when you handwave away complexity. Do future people a favor and don't pretend something is simple if it's truly not. Think about the entire process you went through to get to the point you are and the set of prerequisite knowledge and patterns you have to do what you're doing. Of course, if you want job security, make Alice and everyone else look bad and keep making everything you do overly complex, vague, and with large gaps of explanation.
  • alwaysbeconsing 3y ago
    Well put, and this harks back to the classic Rich Hickey talk "Simple Made Easy". For Bob the process is easy because he's internalized all the complexity. It's not actually simple. But it's subject to the conflation of "simple" and "easy" that Hickey warned about. Another way to it has been put is "beginner's mind" or the "curse of knowledge". Once Bob has mastered the many intricate steps it is hard for him to see them clearly and remember the difficulty he himself had. A truly simple process on the other hand would be (relatively) easy for everyone, not just the expert. And of course as you point out it can be difficult for a removed observer to tell the difference.
• waboremo 3y ago
  This is literally a blog post about not using words like simply, not about reducing complexity or how to share knowledge across progress stages. Some of us in this thread seem to be taking this blog post to project our past experiences onto, but this post is quite literally just about not using words like simply. Also nobody will ever take the word literally from me, I will ensure all docs I come across use it bountifully!
  • zemo 3y ago
    connotation exists, you know
    • waboremo 3y ago
      It does, generally. However you've failed to demonstrate such enough to remain on topic from what the article is actually saying and to what you posted. So much so I would assume you haven't read the article before you posted.
      • zemo 3y ago
        I read the article, you're refusing to see the forest through the trees.
• dingledork69 3y ago
  If you don't understand something then you're in the perfect position to improve the docs. Others who are already familiar with the project may not think they need to document it, because they see it as simple.
  • tomlogic 3y ago
    This is an important lesson. Anytime you're onboarding a new user/employee, your documentation will benefit by getting that person's feedback. What's incorrect? Where there any steps that weren't clear? Or missing steps? Is there information that's outdated? I've even gone as far as forcing the developers to answer questions by incorporating new information into the documentation. If you start having out-of-band communication (email, chats, in-person conversations) between the newbie and the team, there's a strong chance that extra information will never find its way back into the documentation.