[alsfjslkdfgj]

If your diagram is too complex to maintain as code it is too complex to read.

The diagram is not the kindgdom. And it will never be, that's why you see it is so difficult to generate them automatically from the real thing.

...If only we hadn't throw out all the tech writers along with the QA folks when moving to agile.

[dogma1138]

Really? A good example would be a chess board individual moves are easy to read in code (chess notation) a whole board state in the mid game not so much…

[dpritchett]

Depending on your chess engine (e.g. a physical board) a player could reasonably move many times without stopping to update the diagram. Maybe I forgot. Maybe I was in a hurry due to schedule problems. Maybe the diagram editor was offline for maintenance but the chess engine was still open so we kept on playing.

This might soon prove to be A Problem for folks who reasonably yet erroneously expected that each responsible player would of course update the diagram immediately after each move.

[bluGill]

A chess game is over in at most about 60 moves. Sure the game might last for several hundred moves, but by move 60 only a few pieces are left and it is obvious [to experts] what is going to happen. Even in unlimited time controls, the actual time spent one all moves (as opposed to sleeping or doing some non-game activity while waiting for your opponent to move) isn't very long.

By contrast code lives for many decades. While it isn't all modified every day, it is changed often enough.