I agree with everything you said until you got to UML diagrams. The problem with UML diagrams is that they communicate exactly the same thing that the code should be communicating. Class diagrams are not higher-level than the code they describe. Instead, communicate high-level intent and interactions.