I mentioned to a mentor of mine that there are tons of resource for working with people as a manager, but there are so few resources for the nuts and bolts of the job. He mentioned that as he has moved up the organizational ladder, the requirements get more vague because many leaders simply don’t know what they want. The result is that part of the job is creating a dartboard they can start throwing things at to find out what they actually want.
One challenge, coming from programming, is the feeling you’re adding informational debt when you write down some information like a road map or spec. The fear is that you’ll need to maintain some terrible spreadsheet or document over time that will end up being poorly suited and painful to use. When you try out an idea in code, you create a branch. You can run tests and push it to you code repo where it likely you can deploy it to some staging environment and try things out. When it is ready, you get a code review, make some changes and merge it to master where everyone can see it. It is a truly wonderful thing.
It doesn’t help that the person digesting these documents might have different thoughts on what is easy to work with. Slides are often a good medium for some leaders, while spreadsheets are better for other people. Once you get consensus on an idea, you often still have to publish it somewhere. This often ends up being Confluence, where people don’t actually read, or send an email to folks pointing them at a Google Doc, in which case you’ve just started the decay process of the information.
I clearly don’t have a good answer for this. I’d like to try and keep a repository that has our official documents and suggest that we use PRs to discuss topics. With that said, I already see there could be problems with permissions. You don’t want to write up a PIP for everyone to see, so the repository isn’t likely to work. To be honest, I’d be OK with most solutions if there was an end state that was understood in the organization. Knowing some documents are considered living and canonical is really helpful. As is knowing that when they move to some archive, they can go rot safely in the darkness.
The irony with this whole thought process is that when it comes to code, I often found myself telling folks I mentored to move forward with some code because you can always throw it away. This makes me realize that my hangups creating documents for my boss to throw darts at, are likely just an indication that I’m still learning and the best course forward is to practice.