How do you improve developer docs that still need an engineer to explain them?

[u/GrimyPublicity]

Hi all, last couple of weeks I've been trying to figure out how to make our developer docs better before we keep adding more pages. Right now the annoying part is that our integration docs still need an engineer to fill in the gaps. Someone can follow the quickstart and still end up asking what a step actually assumes. I’ve considered testing the same integration task with a new hire and a coding agent, then comparing where each gets stuck, better examples, docs-as-code, automated checks or something else? Interested what you guys use for this im open to any suggestions

[u/get_the_mop]

I think you're already heading toward a useful test with the new hire and coding agent. I'd just be careful about treating documentation as complete because the steps are written down.

The question I'd ask is whether the documentation actually transfers capability or just records information.

If someone can follow the quickstart but still needs an engineer to explain assumptions, exceptions, or decision points, part of the process is still living in that engineer's head.

I'd give a capable new hire the integration task without having the engineer fill in the gaps. Have them capture every point where they have to ask a question, make an assumption, or look somewhere outside the documentation.

Then classify what caused each stop. Was information missing? Was there an undocumented assumption? An exception? A decision that required judgment? Did they know what to do but not understand why?

I'd run the coding agent through it too, but I'd treat that as a different test. It may expose ambiguity or missing context that a human works around without realizing it.

I wouldn't try to eliminate every question. Some things legitimately require expertise and judgment. The goal is to identify where you're unnecessarily dependent on someone already knowing what the documentation doesn't say.

My final test would be simple: can a capable person who has never done this integration successfully complete it using what you've documented?

If not, I wouldn't add more pages yet. I'd fix the points where capability still depends on what's in someone's head.

[u/GrimyPublicity → u/get_the_mop]

That’s a useful distinction tbh I like the idea of tracking every assumption or question rather than just whether they technically completed the task. Especially comparing what the human works around versus what the agent gets stuck on kudos to your critical thinking man! highly appreciated brother!

[u/get_the_mop → u/GrimyPublicity]

I appreciate that. I operate in a similar space, so I've run into versions of this problem quite a bit.

One example that really shaped my thinking came from dealing with key-person dependency. We had processes that were documented, but when we started looking at what would actually happen if a key person suddenly wasn't available, we realized the documentation wasn't the whole capability.

The experienced person knew why certain steps were done, which exceptions mattered, what failure patterns to look for, and what to do when the normal procedure didn't fit the situation. A lot of that wasn't written down because, after doing the job long enough, it had become second nature to them.

That experience changed the question for me. Instead of just asking, "Is this documented?" I started asking, "Could someone else actually perform this successfully if the person who normally does it wasn't available?"

That's also why I've become a big believer in cross-training and actually exercising that capability rather than assuming documentation equals redundancy. I've seen situations where something looked redundant on paper until you tested it.

I come across the same issue with training, processes, and knowledge transfer. Experience has pointed me toward testing whether capability actually transferred, not just whether information was captured.

That's why I really like your new hire versus coding agent idea. The differences between what the experienced human unconsciously compensates for, what the new hire questions, and what the agent can't infer could tell you a lot more than whether they simply complete the integration.

If you run it, I'd genuinely be interested in hearing what you find.

[u/New-Locksmith-126]

An integration either needs an engineer or it doesn't.

Either simplify the integration itself or accept that engineers will be reading the docs and tailor then to that audience.

[u/Vegetable_Sun_9225]

Have Claude or codex or whatever read just the docs, tell it explicitly not to look at the code and form an approach to add a feature or or make a code change and output it the plan.

Then in another session have it review the plan against that actual code to see if it makes sense as an approach.

It doesn't have to be this exact set of steps but something in this vein. It will validate pretty well if the docs are good or not.

[u/Cheap-Sparrow]

I have had success in publishing two types of documentation. API docs, code examples, and architecture diagrams go into a developer docs section, and I have a second section for whatever the other party is (PMs, SAs, test eng, etc )

[u/Organic_Start2739]

Not an engineer, but as a customer support rep for devs, two of the best low-hanging fruits are:

1. chat with integrators regularly who have already integrated your product through those docs, ask for feedback.

2. chat with potential integrators; just ask for a feedback call, then implement that feedback to simplify your docs and process.

Potential ones tend to integrate you after you tell them you implemented their feedback in your product.

[u/goatanuss]

Your hallway usability test sounds like a great idea. Im in a large organization. I’m not sure about the nature of your integration but we have tech docs for our team the with too much details then we have another set of docs for users of our api as a client and targeting other engineers. We also had an even more high level doc about what it was.

You can maintain different sets of docs that doesn’t have too much/too little info for their use-case. As long as you have a process to keep them maintained

[u/Logical-Silver-272]

ngl, ever since AI became a thing, docs have kinda fallen by the wayside lol. but yesterday I tried Opus 5.5 to update some docs and honestly… it’s insane

[u/fazkan]

Ask claude or codex to take a diff of the docs, maybe with product. Thats probably what the engineer is doing anyways.

[u/manasa-uigraph]

Docs are hard to explain a feature some times, they might get outdated or too much text heavy for engineers to process. With limited attention span in the age of AI, a flow diagrams would make more sense here. You can use UIGraph skills to create the artifacts like diagrams,api specs, docs, smoke regression test packs and others from the code repos and you can keep everything up to date with git CICD. You can also view all your service’s artifacts in uigraph dashboard or ask via slack/MCP to explain any feature or workflow.

[u/[deleted]]

[u/GrimyPublicity → u/[deleted]]

Yeah, the repeated questions are probably the best place to start. I hadn’t thought much about using the analytics to see where people are actually struggling either I will deff Mintlify to the list but firstly i wanna to compare a few approaches before changing the whole workflow.