Comment by tikhonj
6 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.
I currently use the separate md file to capture the mermaid diagrams about the code, it helps to get overview of the file and various scenarios. It is good to keep all documentation ideally part of the same code. But if documentation is more as part of the code, passion to read source file is reducing, for me.
*_learnings.md: I am also using one more _learning.md, that captures what agents learn while building this file. it depends the complexity of the source file. mainly if the source files is about low level, protocols and so on. even separate _learnings.md also helps. so have now. _learnings.md may be needed how much investigation we have done to produce a working protocol.c.
protocol.c, protocol.md, protocol_learnings.md
> 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.