I’ve always hated the idea of UML, so it’s good to hear that prominent engineers hate it too.
I did learn an important lesson at ObjectSpace. A UML diagram can’t push 500 pages per minute through a RIP.
UML does not deserve its own format. It’s an over-engineered, graphics-laden piece of paper to convince others that programming work is being done.
The weird thing is, an API already does that, and it does it in a way that’s immensely helpful to programmers. The Java Docs are fantastic. You can click to drill down into packages, classes, objects, and methods. PyDocs, RDoc, and every other major language has a similar ability.
The API is an interface for other programs that build on the code base, and the API documentation helps programmers manipulate the code base. The crux of any library is which functions to call, and which kinds of objects those functions return. Anything more than that, and I’m overwhelmed with useless information. Anything less than that, and I’ll never know where to start.
APIs are necessary for Web 2.0. Without an API, there’s no efficient way to manipulate data, so handmade HTML scrapers must be written.
API docs these days appear as HTML files, but they could take any form. UML files typically require a special UML-rendering program, yet another obstacle to progress. UML diagrams are visual, but in a bad, literal way. Because API docs use HTML, it’s easy to navigate them by clicking links. UML requires panning, scrolling, and zooming. HTML’s quasi-hierarchical view is just more efficient.