Proposed Solutions

[00:00:00]
>> So I'm hearing what you're saying. And also a lot of people echoing in the chat have like, the challenge of having to do them the mental gymnastics of write the code in the repository over here. And then write down a description of the code that you wrote in a completely different platform.

[00:00:20]
>> Right.
>> And yes that there's some solutions like just as you had mentioned acknowledging that it's important to write docs. I think that requires a level of discipline. And if teams for whatever reason aren't adopting that level of discipline, the problem will persist. And th is all just that it really resonates with how we are approaching solving this problem.

[00:00:57]
We're starting to stand up a tool called Backstage
>> I think I know what that is, yeah.
>> It was originally implemented at Spotify.
>> And building something like that.
>> Yeah they open sourced a bunch of what they've built for for internal use. And a big part of it is like a documentation.

[00:01:17]
Think of it like a virtual centralization of all the documentation so you can pull in readmes you can pull in things static documentation that was built with make docs. You can write your own plugins to pull in wiki content or you can write your own READMEs or whatever you want.

[00:01:39]
So that's kind of the avenue we're exploring where we've got the fragmentation. How can we at least unify it so that it makes it more easily indexable, but teams can still manage it in a way that's ergonomic for them. It's co-locating the docs next to the code so that it's more likely to stay up to date so.

[00:02:02]
>> Yeah, wow, okay.
>> So great conversation and reassures me that yep, we we're listening to our customers and we're hearing what they have to say.
>> And, right, yeah. Okay, and this is what I love about writing documentation is, when you start getting comfortable with it, you start finding yourself like, okay, I'm ready for the next step, right?

[00:02:24]
So what I would say is, what is our proposed solution, right in this case, right, and it doesn't have to be technically, right? But I think one of the things that we need to propose across the company as an organisation is standardisation and culture around these issues, right?

[00:02:43]
And I think really the bigger one rather than standardization is really just culture, right? As I said before I've written documents where it's basically been, hey solve a technical problem and then I've had to be like yeah this isn't a technical problem. [LAUGH] This is a culture problem.

[00:03:00]
You need to be able to write that as your first line and be confident that you're going to go into a meeting with that. Be like listen, we could do I can make pigs fly if you want, but it doesn't mean that like it's gonna solve our problem.

[00:03:15]
And I do think that hands down before going anything else culture is going to be a big one here. Whether it be culture of making sure our co workers are creating tickets. And making sure that we have like again, I actually love the idea of keeping it close to the.

[00:03:35]
>> Essentially, contextually what you're working on, but it's harder, right? And so you need to be aware of that. Okay, we're doing this purposely. If anybody brings up why we do this, it's because we want that information to be consumed quicker, right? And so that's going to be culture around that.

[00:03:52]
The next thing I would say too is improve standards for messaging, right? We talked a bit about how we want messaging to happen. So we're going to need to improve standards around it. Again, when a problem is raised, making sure because it's not just like an overall culture problem.

[00:04:14]
But we really need to make sure we're still tackling the topics we've discussed. And sometimes even though it sounds like these may be, twice, it doesn't matter. We're iterating that this is a huge problem, right? And this is impacted by that problem, right? And then I would say as well improve standards around linking information, right?

[00:04:39]
And this could be something as simple as saying like, okay, we are going to decide to put things in different places. How are we gonna link these things, right? How do we make sure that when we send out an email that it always gets back to the place that it needs to get to, you know what I mean?

[00:04:56]
So again, this can be our emails, or so? Yeah, our emails basically, this is our messaging, right? And here is really where we talk about our documentation. And you can see how we're kind of addressing these problems. The one that we're not going to go into because then it gets, [LAUGH] It probably would make this document 10 times bigger is what solution we would write our documents in, Rright?

[00:05:29]
I would leave that to you guys because again, I would say we are open to fragmentation of documentation, but want to provide the best tools, right? Like, what did you say it was called again?
>> Backstage.
>> Backstage, right, backstage to be the GLUE of these information, right?

[00:05:51]
And I think that like this is the biggest takeaway. That we need something that's going to be the GLUE of all of that. And if we have that GLUE as well as standards around linking, as well as standards around messaging, and making a good overall culture of just documenting things.

[00:06:12]
Then there's a solid chance that at least it won't be as crazy as it was before and hopefully you can start taking steps forward. Again, these are very simple, proposed solutions here, but this helps us at least get us in the mindset of it's not a technical problem.

[00:06:29]
We got to fix this. There anything else we feel like we would add to this proposed solution? Cool, if that's the case, then realistically, what you should be able to do is take this and then take it to your team lead. Take it to more friends don't just go directly to the team with that because they will shred you alive.

[00:06:56]
Yeah, I would at this point, I would go to a coworker and be like, hey, what do you think of this? I would have the same conversation that we had or that we had, and break it down and be like, man, I didn't think about that. Go back, do it a couple times.

[00:07:09]
And then by that point, we'd be good.
>> Just to comment from chat.
>> Yeah.
>> Institutional knowledge should be treated with as much respect. There's tangible assets or even revenue yeah but there's no process or pipeline around maintaining cultivating and proliferating institutional knowledge the whole organization suffers.

[00:07:29]
>> Yep, and that is money literally that's money that people. A lot of the business just doesn't fully realize because the developers aren't portraying that enough. And saying this is money guys you're gonna either hire somebody new or you know I'm gonna do it for you, but yeah.

[00:07:47]
[LAUGH]