Docs-as-code is not development
Working with developers in a docs-as-code environment can lead to some undesired and time-wasteful consequences.
You author in IDEs, use version control, create elaborate pipelines and automated workflows, and maintain the tooling. Then during SME reviews or stakeholder alignment you frequently end up defending arbitrary engineering decisions of your tooling stack instead of reviewing the content.
The users of my API reference do not care if I had a neat commit message or a ticket number. Or if the pipeline passed all twenty Wiz checks introduced by the infra team. Checks that check everything in my repo but have nothing to check since I do not touch production code. Or use the same stack.
The users care about usability. About getting to the correct, helpful data in a way optimized for them.
Programmers overengineer simple concepts. It's natural. There is no off-switch for the way someone thinks. That is why conversations take a side-turn towards what interests, or bothers, their inquisitive, spectacular design mind.
The same way product managers ask for a specific type of content in a specific place of the website. They already know what they want. But they provide very high-level context of how the feature is supposed to work. No technical specificities, or what the users will experience. And I get it—it's not their job to develop it, but to design the product with the most business value and align everybody on where we are supposed to go.
However, the scrutiny your docs are put under needs to be directed. Reviews and feedback are great. But the lens needs to change. The standards cannot be the same for every repository, application, or product.
So what do we do?
As technical writers, we get to the gist of it. Analyse it all. Distill the essence and pass it on to the users in plain language and intuitive testing resources. We all know this.
The challenge is to manage expectations from the team as well as users. Because dealing with your team is as important as dealing with the users.
Educate the team. Do not condescend but actually explain. This requires changing their perspective and is genuinely hard to do. You are meant to do what good leaders and product managers do weekly—make sure everybody is on the same page and understands each other. Be clear, in an empathetic, helpful way, about your purpose, approach, what the benefit for the user is, and how you get there from the chaotic amalgamation of tickets, PRs, and meeting notes.
This is why certain very successful technical writers transition into leadership roles. Not because of the natural progression of the career ladder. It's because they realize the benefits of being successful in getting everybody to work together towards the same goal with a clearly understood plan and deliverables. This is the point. The very skill that will steer that conversation where it needs to go, not discuss why this SSG choice over the latest FE, CMS wonder, but get to the essence that the users need.
You might have already experienced this—being asked about advancement and then offered owning a project that seemingly does not really fit with your current IC job. That was the leadership vetting you. Testing whether you'd be able to align everybody and make them productive on a smaller-scale project.
Whether you want that job or not is another topic. But the skill to get you there is the same, and worth investing time in. Learn how to manage expectations, make everybody understand each other, and work towards the same goal productively. That's it. Sounds simpler than it actually is though.
The trick is to do it on a smaller scale. You'll have an easier time the next go around. Iteratively. And on a scale of years, not quarters, the benefits will be palpable.