'If you do a search in the article for the first reference, you'll find where Phil states "Remember that, like Marcel Proust's 'À la recherche du temps perdu', everyone will think it wonderful, but nobody will read it."'
Thanks Jeff. Absolutely right.
In the question of using JSON, I don't use it because I think it is wonderful, but just because it can be read by almost anything. It is like speaking English. It is not that it is pretty, just that it gets understood. I discovered that it was a good way of documentiung databases entirely by accident. I was doing a series of articles on Flyway. It is a product that intrigues me, but a migrations approach isn't a good way of approaching database documentation. Where do you find it? It isn't with the build script because there isn't one. it could be anywhere in any migration. I was forced to do it but then found it was quick and painless and it was easier to stash in source control.