from Hacker News

Ask HN: How do you document your Data Models?

by pierre on 7/14/22, 8:13 PM with 2 comments

When documenting my last project I came to the realization that all projects I have worked on have a very poor documentation of their data model. I believe that this leads to longer onboarding time and a lot of newscommer mistakes in the project (such adding new properties for something that exists somewhere else). Generally the data model is documented in the database / ORM, but it generally describe the physical representation of the data in the database (name is a Varchar(128)) but not how/for what such data are to be use (which is sometime complicate to understand on old project where knowledge has been lost and when naming is not consistent/explicit).

It seems that recent ORM that allow you to describe your DB schema as code (like Prisma) allow you to add ‘comments’ on your Data model, but I feel it’s not enough.

I have look at the data modeling tooling but haven’t found satisfying solutions.

I missing something? How do you document your app data model?

  • by dmfay on 7/14/22, 9:44 PM

    Postgres schema comments (COMMENT ON COLUMN mytable.mycolumn IS 'spline reticulation coefficient'). Otherwise, I've given up on ever maintaining data model documentation and generate ad hoc graphs from different perspectives in the foreign key network: https://di.nmfay.com/exploring-databases-visually

  • by fmakunbound on 7/14/22, 9:04 PM

    Well, we take a distributed approach where I work currently. Some of it is in an Excel or a Google Calc spreadsheet, some in Confluence, the project README.md, random Git comments. Sometimes we annotate the classes in the code with documentation and sometimes even generate the documentation from that. It’s all a little confusing TBH. Some of our models are cross domain and have meaning depending on context.