How to Create Good Technical Documentation That Engineers Actually Use
AI is everywhere now. From helping you code faster to summarizing documentation, it feels like every engineering team is trying to figure out how to use AI. But here’s the kicker,even though AI is helping developers work faster, it might actually be hurting software delivery performance. Sounds wild, right? On the Engineering Success Podcast, Nathan Harvey from Google DORA and Rishi from DevDynamics unpacked why this is happening and what it means for teams.
AI speeds up but also creates new problems
Nathan laid it out bluntly:
"One of the best things about AI is that it keeps developers in the flow. But it also makes it really easy to write way more code in the same amount of time. And that’s not always a good thing."
Why? Because more code means bigger changes. And bigger changes are harder to test, review, and deploy. DORA’s research shows that the most successful teams ship small, frequent changes. AI might push teams in the opposite direction.
"When you’re pushing giant chunks of code, your pipelines slow down. Testing gets more complicated. Rollbacks are harder. It’s a chain reaction that hits your delivery performance," Nathan explained.
The context problem with AI
AI doesn’t understand the context of your specific team or business. Sure, it’s trained on a massive dataset, but that’s not the same as knowing your company’s policies, architecture, or goals.
Rishi shared his experience:
"I use AI all the time for code assistance. It’s great for boilerplate stuff. But when it comes to writing something with complex business logic, AI often makes mistakes. Debugging that takes longer than writing it myself."
Nathan agreed and added:
"If the AI doesn’t have context, it’s like having a junior engineer who’s smart but doesn’t understand your system yet. You have to check and fix everything."
This lack of context can lead to inefficiencies. Teams spend more time cleaning up AI-generated code instead of delivering value to users.
The positives AI brings to the table
That said, it’s not all bad news. AI is still helping in plenty of areas. Nathan highlighted a few big wins:
- Documentation: "AI makes writing documentation way easier. It’s not perfect, but it gives you a starting point so you’re not staring at a blank page."
- Technical debt: "We’re seeing AI help reduce technical debt by automating some of the boring but important tasks, like refactoring code or catching bad patterns."
- Developer flow: "AI tools keep developers focused. You don’t have to stop and Google something every five minutes when AI can surface the answer right there in your IDE."
Why delivery performance is dropping
So if AI is so great, why are delivery metrics getting worse? Nathan shared two hypotheses:
- Bigger changes: "Teams are shipping larger chunks of work, and that’s slowing everything down. You’re losing the speed and stability that comes with small, iterative changes."
- Over-reliance on AI: "AI doesn’t replace human judgment. If teams lean too hard on AI without checking its work, they’re going to end up with more bugs, more rework, and slower cycles."
How teams can use AI effectively
Rishi and Nathan shared some advice for making AI work for you instead of against you:
- Keep changes small: "Even if AI helps you write a ton of code, break it down into smaller PRs. Don’t push massive changes all at once," Rishi said.
- Train your AI: "Enterprise-grade AI tools let you train models on your own codebase and policies. That’s a game-changer because now the AI understands your context," Nathan explained.
- Use AI for repetitive tasks: "Let AI handle the boring stuff,documentation, refactoring, boilerplate. Save the tricky logic and architecture decisions for humans," Rishi suggested.
- Iterate and experiment: "We’re all still learning how to use AI. Treat it like any new tool. Test it, see what works, and adapt your processes as you go," Nathan said.
Final thoughts
AI is shaking things up in software delivery, and the impact isn’t all sunshine and rainbows. While it’s speeding up individual workflows, it’s also introducing challenges like bigger changes and context gaps. The key is using AI strategically. Don’t let it push your team into bad habits.
As Nathan put it:
"AI isn’t here to replace engineers. It’s here to amplify them. But if you don’t manage how you use it, you’re going to see more problems than progress."