Problem: Fragmented Documentation

[00:00:00]
>> I do want to do a couple of things. I wanna do a couple of experiments with you, guys. Because I wanna make sure that you guys really feel confident in making a technical document. As we kind of just said, it's a lot of what you're gonna do in DevOps.

[00:00:16]
It's gonna be the thing that you start with the most. So what I'd like to do is I'd actually kind of like to do an interactive TDD, where we'll actually create a technical document. We'll break it down, and we'll try and find a solution for it, so let's do that.

[00:00:34]
So I'm gonna quickly hop over to Notion here. Okay, so I don't necessarily have a problem, because I want to get a problem from you guys, okay? Now it can come from chat, it can come from here, I don't really care, but we just need a problem to solve.

[00:00:51]
And I think we all have problems to solve. [LAUGH] So I think we could find one, but we really wanna try a very simple problem to solve. This could be logging, this could be containerization. It could be deployment, could be automation. It could be something you deal with at your company right now, right?

[00:01:09]
>> Fragmented documentation, perpetuating tribal knowledge.
>> Whoo, that's okay. So you're saying fragmented documentation with what?
>> Perpetuating tribal knowledge.
>> If I can spell that right.
>> That's right. [LAUGH]
>> Okay, so I was just given a prompt. I'm a DevOps engineer. We have fragmented documentation with perpetuating tribal knowledge.

[00:01:39]
Okay, so let's take a look at that. First, we're gonna say, oops, what problem are we trying to solve? So can you give that to me in a sentence of what the problem is, basically?
>> Engineering teams are frustrated because they don't know where to find answers to their problems with their day to day work.

[00:02:10]
>> Okay, so engineering teams are frustrated because they are unable to find information regarding, what were you saying?
>> Their day to day work.
>> Okay, their day to day work. Okay, engineering teams are frustrated because they are unable to find information regarding their day to day work.

[00:02:30]
This is actually a very common problem. I deal with it all the time, right? In this case, I think it's good to start with, how do we share information, right? So how do you share information right now? If you don't mind me asking in this scenario.
>> We've got wikis, we've got blogs, we do email blasts, we've got communication tools like Microsoft Teams.

[00:03:02]
>> So okay, so like a messaging software. Okay, all right, so let's break this down a bit. You said that we've got wikis, blogs, email blasts and messaging software. First thing that kind of stands out to me is what do they do, right? So in the circumstance of wikis, what would you say the wiki does?

[00:03:27]
>> I would say generally, our wikis contain our best practices for using shared solutions.
>> Okay, cool, so basically, it's focused on cross team knowledge and how you guys solve those problems. Okay, cool, and what about the blog?
>> Blogs are usually used to communicate releases or new features being introduced into shared solutions.

[00:04:03]
>> Okay, and here's a question, with regarding to the blog, who does the blog serve?
>> Generally, engineering teams, generally, individuals with a software engineering role.
>> So this is internal.
>> Yes.
>> Okay, cool, okay, email blasts?
>> These are usually an announcement slash call to action, some action is expected of teams or it's more important that they're aware of some infrastructure change that we're rolling out.

[00:04:46]
>> Okay, oops, [INAUDIBLE] that will impact, okay. And then messaging software.
>> These are gonna be the individual troubleshooting threads that are very difficult to parse and look for patterns across threads.
>> Trust me, [INAUDIBLE]
>> We would definitely want to identify those patterns, tease them out so that we can better empower teams to self service.

[00:05:22]
And if there are common issues, then we need the insight to those common issues so that we can solve them for everyone. Instead of continuing to just solve one off issues for this team and then the same kind of issue for another team and then a third and a fourth.

[00:05:43]
>> Gotcha, so would you say that a lot of what's happening in the messaging software is kind of like, one-off solutions that never get documented?
>> Yeah, that's a good summary.
>> Okay, cool, so. Cool, so looking at this, that's a lot of different places to get information from, right?

[00:06:14]
That would be something that I kind of immediately see already. I think what's really interesting is the next thing to ask ourselves is, Which of these benefits is the most, right? So sure, we have a wiki, we have a blog, we have email blasts and messaging software. Which one are we seeing actually help the company the most?

[00:06:45]
Which one are we seeing developers actually using the most would be my next question.
>> Heaven knows. [LAUGH]
>> [LAUGH] That's fair, okay, so.
>> I think what we're frankly lacking is a lot of metrics, like usage metrics. We don't know, are people consulting the blog where we also have a lot of information that overlaps with wiki content?

[00:07:09]
Are they just reaching out on our messaging software and asking teams directly instead of going and reading the manual?
>> Yeah, awesome, okay, so basically, it seems in some ways what we're kind of already starting to recognize is, we do share information but we're not really sure if it's the most effective way of sharing that information.

[00:07:37]
Yeah, so yeah, I think that if we stopped here for a second, right, this happened actually at my company which is ironic. We were in the same problem. Again, I think this is a fantastic prompt. Do you know what our first decision was to do before we even wrote a technical document?

[00:07:58]
Create a discourse because why not? [LAUGH] That'll solve our problem. And that's what we did. We initially just didn't think about it. And we just said, whatever, we'll put a discourse out there. Do you know what happened to the discourse? Nobody used it, never got a single article created in it and it's probably just still sitting there as an empty container at the moment.

[00:08:17]
[LAUGH] And the reason why I bring that up is because of this right here. Yeah, hands down, right? If you ask this question and you have no idea what is even helping you, how do you know where to put the best solution for the problem, right? And like you said that there's no real tracking around what's being used, right?

[00:08:44]
You don't know if information is being shared in multiple places, right?