Pain Points

[00:00:00]
>> Okay, so, what we've talked about is so far how we share information, right? Which of these benefits us the most, and then basically what we prefer. So there's a couple things that are still not really fully solved here that we can talk about. Does anyone know what one of those things might be?

[00:00:23]
Maybe what is that one unsolved thing that's still sitting here? I'll give you a hint, my cursor's on it [LAUGH].
>> Can't track what people use, I guess. And if you're talking about a centralized documentation platform, we've tried and we've used stuff like that. We don't really talk a lot about the cons of it in this document either.

[00:00:42]
And that once you separate the documentation away from where the problem is, it becomes way less likely to be managed. And you can talk about idealistic culture, and then there's also the reality of what people use on a daily basis.
>> Right.
>> And I think that could be reflected in this document as well, too.

[00:00:59]
>> Yeah, I agree. Okay, so, let's talk about it then. We've talked about the pros. What are the pain-points we've dealt with, yep?
>> Someone in chat said that some developers may or may not like writing documentation. And generally, it's taking away from the time that they have to do their deliverables, unless there's actually time accounted for and it's treated as a deliverable.

[00:01:31]
>> Yeah, okay. Yeah, that's a good one. I can talk about that cuz it's very similar to what she's talking about as well. Most of what we've said so far is culture, right? [LAUGH] It really is. I would argue that no company is too big for two things, testing and documentation.

[00:01:56]
If you're not testing, you're doing it wrong. If you're not writing documentation, you're doing it wrong. There's that whole argument of doing test-driven development. Yeah, TDD, thank you. [LAUGH] Yeah, how many companies shoot that down because of the time, right? Well, you can also argue that that time invested can save you a lot of time, [LAUGH] you know what I mean.

[00:02:24]
Having well structured tests around them and things like that. So, it's a fair pain-point. But I would also say that I don't if it's one that you would want to just not think about. The reality of this is engineering is about knowledge sharing as much it is about building things.

[00:02:48]
And I think what culturally you're not realizing is you're not doing justice to the team when you're not sharing that information. And that's something I had to learn in DevOps, because I went out and changed our whole CI platform one day, and nobody knew what happened. [LAUGH] And then I had to spend the next three months explaining everything, writing it down into technical documentation and stuff like that.

[00:03:14]
I do wanna get into some more of these pain-points. I would love to know more of what your thoughts are on those pain-points, cuz it seems like you've definitely gone through them, so hit me. What do you got?
>> Yeah, I don't know. This is just a general complaint about people that they really hate duplication to a point that it's flawed.

[00:03:34]
And that instead of just having that information pointed at it in multiple places, or like, okay, you could have that blog but we also reference it in the Slack channel, and it'll also be this email blast.
>> Right.
>> That's a better way to centralize it because you've got people who check your email, you got people who check Slack, you've got people who have their wiki bookmarked and just always use that.

[00:03:49]
So instead of trying to force everyone into one solution, you could just let people trail in their own way, whatever you wanna do. And whenever I've used a centralized documentation platform like Atlassian Confluence or Notion, it becomes this outdated, disorganized mess really fast, and nobody wants to deal with it.

[00:04:11]
And it's just like, okay, well, this is about this project that should be near the project. And if you try to make a note documents because it was like, we have this new note document and we got to use their note documents thing. And then you don't do it in the right places in the right circumstances, people just go, well, I didn't really like that.

[00:04:34]
A lot of them have terrible searching, so you can't actually find what you're looking for.
>> [LAUGH] I feel like you're just talking about Confluence [LAUGH].
>> I've had the same problem with Notion. I've used both and I hated both of them.
>> That's fair.
>> I don't do any of that.

[00:04:50]
I search everything through Slack, and everything that we do is through Slack. Because everything could be found in Slack, I can search it in Slack. I know somebody talked about it in Slack, it's got live problem solving. And the way that some people who like more documentation than others deal with it is they like daily notes about what they're doing.

[00:05:08]
They have got their own repos where they take notes and they upload it every day. And you can track their work through entirety, and that works for them. And that way you're not spending time. I think the complaint about developers not writing documentation is, people have this idea that it has to be this massively organized, perfectly written source of thought that is presentable to the board or something.

[00:05:31]
That's not the point of it. I think if a basic person can follow it, you're doing what you need to be doing.
>> Yeah.
>> Also if your company is not letting you do documentation at the basic level, maybe stop pointing as much, I hate points also.
>> Yeah, [LAUGH].

[00:05:49]
>> [INAUDIBLE].
>> No, hey listen, I actually have not said this live publicly yet, but I will. And now that everybody's watching me, I actually believe that pointing ruins software development. I hate to say it but it's such a random number that developers don't actually care about. I've never point at something and then been like, yeah, I'm gonna get this.

[00:06:16]
I don't really care, I'm only doing it because you want me to, [LAUGH] you know what I mean. Super fair, yeah, super fair. So let's talk about these a little bit, right? In your mind, why do you think we have duplication?
>> I think a lot of duplication serves a purpose.

[00:06:37]
I don't hate duplication, I think other people hate duplication.
>> So why do you like duplication?
>> Okay, I'm trying to rephrase this in the right way. Instead of trying to force everything into one little box that makes sense in this one central area, you can have things that are only related to the thoughts that are relevant at the time.

[00:06:59]
Or you could just reference that other document, for more of that stuff, look it over here. We cover some of it, but this one is really about how to start up the app.
>> Is that duplication?
>> A little bit, you can cover the same topics. I think s lot of people were like, well, that's about this service, so it should all be here.

[00:07:15]
And you're like, well, this blog was for our support engineers to figure out how to answer customer questions.
>> I see.
>> And this blog is all about this really just for the engineers to say, this is what's gonna change about your development, that doesn't need to be in the same place.

[00:07:29]
>> Sure.
>> Yeah, it's the same release, but different information for different people. And you can reference them both and be like, hey, if you're more interested in this part, go over here.
>> Go over here, yeah. So then would you say that really what we hate is duplication of documentation that says the same thing?

[00:07:48]
>> Yeah.
>> And we prefer to have what we'll call links to contextual thoughts around maybe problems or something like that. I guess what I'm trying to get at here is just, we need to understand what duplication is and how we're gonna utilize it. And as I said before, we can use any of these things.

[00:08:15]
But we can't go into the discussion of just saying, it works for us, right? We have to understand why it works for us, right? So, I guess in this mind set, preferring to have links would be maybe, like as you said, maybe there's a DevOps section, right, that focuses only on infrastructure changes, right, and stuff, I can't spell, structure, changes, and stuff like that.

[00:08:42]
Maybe there's the frontend section, right, and that's focused on logical changes pertaining to the developers, right, and things like that. So I guess one follow-up question to that is, would we still want these to exist? Cuz I could still see this in a centralized place, just with better organization.

[00:09:08]
Would we in this scenario, how do we care about linking, right? Do we care about everything being in a Slack thread versus, you know what I mean, things like that?
>> I don't care as long, as it's close to where you're trying to use it.
>> It's close to where, can you define what that means?

[00:09:25]
>> I am trying to run the code, but you'll change something running locally, right? I don't wanna have to go to a different app, look for the instructions on the latest release. It should be near the code that it's relevant to.
>> Got you, so we're basically keeping information as close to implementation.

[00:09:44]
>> Yeah, if you put it in a totally separate area, it just.
>> Okay, well, I feel, at least by that conversation, we have a better understanding of what duplication is now, right? And so, I would agree with you. I would actually say, okay, you know what, this is a possibility of saying duplication is actually good, as long as we follow these standards, right?

[00:10:06]
Because I think one of the things that's very easy about duplication is, copy paste, copy paste, copy paste, copy paste, right?
>> Yeah, the caveat to that statement is, if you're putting the exact same thing in two places, then it only updates in one place when somebody updates something, and then you've got different things, not that.

[00:10:23]
I just mean, I don't hate making the same announcement in a channel and an email blast.
>> Sure, yeah, absolutely. You got to get it to the people's eyes, and I fully agree with that, yeah. I think my focus was what you said, the other part of, cuz that is a big problem.

[00:10:40]
Do not keep the same information in multiple places, right? That's really my big frustration with it is, okay, I'm looking at this, okay, I feel great. And then I read the readme, which is right next to the document and I started it and it died, [LAUGH] right away.

[00:10:59]
Yeah, that one developer didn't realize that the readme is actually in the repository. So they put it in Confluence, sorry about that. That's the culture I think that we're trying to focus on here and avoid. Okay, so, really quickly, centralized documentation, we'll say it can be a mess, sorry, it can be a mess, and is lost.

[00:11:23]
Why can documentation be a mess? [LAUGH] Can anyone put that in a simple sense? [LAUGH]
>> No plan and disorganization, just no maintenance.
>> No planning, no standards, no maintenance, right? I think that this is something that's also massively overlooked. Is, you can't have a warehouse and then not clean it and take care of it from time to time, right?

[00:11:53]
And even if we have it in multiple places, and this is a pro and a con, it's something you can think about. If we have everything in one place, it's easier to update these things, right, because we can easily just find it in that one place. If it's in different places, that's fine, but we need planning around that, we need standards around that, right?

[00:12:15]
We need to be able to say, okay, well, it's on the blog, we got to update this and then it's over here, we need to update this, we got to do this. We have to have a structure around it. And I'm sorry to say this, but honestly, this one here is just negligence.

[00:12:33]
That's all it is. It's just negligence. It's the company not realizing that their main depot of information is their most valuable. And it's being kept in what you mentioned, all the way at the top, perpetuating tribal knowledge, right? We haven't even really talked about tribal knowledge, but it's mostly because we don't want to, right?

[00:12:58]
We wanna talk about, to get rid of that because tribal knowledge is not good. I know it seems like it might be, but tribal knowledge is really not good. If a person leaves the company at any time, you're screwed, [LAUGH] you know what I mean.
>> There's a fine line between tribal knowledge and domain knowledge, and specialization.

[00:13:16]
>> Exactly, yeah, exactly, exactly. Tribal knowledge is, yeah, man, he was here five years ago and the database just works like this. I don't know, ask him. That's tribal knowledge, right? Not the domain specific knowledge of, we use Postgres because it indexes our queries for us the right way, and dah, dah, dah, dah, dah, right?

[00:13:35]
So we want to avoid that, right? And we've already kind of handled that a bit, right? We've said that with messaging software, we're gonna avoid tribal knowledge by just creating an issue or a ticket, right? Putting it somewhere where things are being written. And whether it be centralized or not, right, we can just say documentation platform, right?

[00:13:55]
Same thing there. Encouraging your co-workers to, anytime you find yourself in a scenario where somebody is like, that, be like, cool, write it down. [LAUGH] You know what I mean, because when they do that, they won't forget it. Here's a good example of that. At my company, we've had this thing where QA creates a lot of their own AWS credentials, which we deal with.

[00:14:23]
[LAUGH] And so we have automation around those policies and stuff, though. However, it's a manual connection of attaching the policy to the role. And that gets kicked out for some reason, we haven't discovered why but the role just randomly gets removed. So, for about a year, [LAUGH] every three months without us realizing, QA would come up to us and be like, hey, our credentials have expired.

[00:14:51]
We had no idea what was going on. Finally find out that the role got kicked off of it, right? Well, somebody forgot to write documentation on it, for the next time, we dealt with it. And so I saw a Slack thread coming in few months later, same problem, and I literally just went, is this the same thing we just dealt with?

[00:15:12]
And then, again, somebody on my team went, write it down. [LAUGH] And literally, what did we do going forward? We didn't solve the problem, I can say that holistically, we didn't. But we gave a path that we can move forward with the next time this happens, right? It has become tribal knowledge that this is what happens, however, I'm impacting somebody that doesn't know that tribal knowledge, you know what I mean.

[00:15:38]
So it makes sense for us to write it down, basically.
>> I mean that, and if you think you're gonna remember something in three months, you're not.
>> Yeah, I'll do three days. [LAUGH] Yeah, I agree. Having the assumption that your brain is as good at storing variables as a computer is wrong [LAUGH].

[00:15:57]
That's why ChatGPT is being created.