Comment by tikhonj
3 hours ago
Why not put the content from the md file in the code as documentation?
Ideally, the code can actually help you structure that information. I've written a bunch of Haskell and OCaml like this, where the types in each module let me structure my documentation in a way that is actually easier for people—and maybe also LLMs—to track. As a bonus, it makes it more natural to keep the two in sync.
> why not put the content from the md file in the code
We do that :-)
https://joist-orm.io/modeling/documentation/#two-way-syncing
Technically the md file can have more free-form docs, but for the overview/fields headers that, by convention, map to the entity/field jsdocs, we do sync them over.