Ask HN: Documentation and diagrams versioned with code – how to handle diagrams?

Versioned, text format diagrams.

Alternately as mentioned, the mermaid DSL or similar, but this is daunting for non-technical users. I'm more a fan of having people be able to think and communicate visually, as the technical users are both the least likely to need the visuals, and if capable of creating them, the visuals are less valuable.

Mermaid is a great output format for documentation though if you're rendering these from API/code.

My take is this.

Some of the content of the "diagrams" can be derived from the code (for instance you can get the methods and fields names and types of a Java class) There is certain extra metadata that it takes to make a good diagram that could be stored in a separate file in a textual format which plays well with version control. A generator script puts it all together to make the images.

Some of that metadata is: do we draw this object? where do we draw it? how do we route lines to connect it to other objects?

i think you need to be able to make more than one diagram (a UML of 100 database tables takes up most of a blackboard panel, a diagram that shows how 5 tables work together to support a user story is golden)

there is a tension between automatic layout and routing which will usually be unacceptably bad and manual layout which is a lot of work (I love boxes & arrows in Powerpoint except for the Bézier curve connectors... then I learned my favorite anime illustrator doesn't know how to draw anime characters with Bézier curves either.) This is an area where you need to find a compromise that works.

In the 1990s there was interest in tools that could parse some code, manipulate it in a UML-like interface and round trip it back to code with whitespace and comments intact so that it makes changes about the same as a professional programmer would that you can check into git just like another team member.

That path requires unusual compiler technologies, but you can also use canonical sort orders and similar tricks to make data in some format like YAML evolve in a way that plays nice with git.