If I were given an electrical design, I would expect a schematic, a parts list, a board layout, and a theory of operations" - a prose document explaining why th

If I were given an electrical design, I would expect a schematic, a parts list, a board layout, and a theory of operations" - a prose document explaining why the rest of the stuff is the way it is. My last job, there was the code itself, and there were UML class and sequence diagrams. But there wasn't anything like a theory of operations. That made it very difficult to learn, because it was so object oriented that you couldn't tell what anything actually did. Or, more to the point, when you needed to make a modification, you couldn't find where to make it without heroic feats of exploration. So I think that's the great need. A human needs to sit down and write out why the code does what it does, and why it's organized the way it is, and where the parts are that are most likely to be needed, and where to make the most likely changes. I'm not sure an AI can write that - certainly AIs at the current level cannot.