Comment by stephen

8 hours ago

I've also been a little-d DDD fan, and we've had luck with per-entity `md` files to language-independent document domain behavior/quirks/usages.

I.e. an `Author.ts` has an `Author.md`, `Book.ts` has an `Book.md`.

For agents, we've given them a skill to read & write the `md` files:

https://github.com/joist-orm/joist-orm/blob/main/packages/co...

And so agent-written `md` updates are showing up in PRs. So far it seems useful (our main repo is a 350k LOC TypeScript monolith).

Admittedly, this is way less sophisticated (& less complicated) than the "graph of edges in/out of every bounded context" in the OP, but that is probably again my "little-d" DDD perference, where I find some of "DDD at scale" patterns lead to, imo, over-engineering.

3 comments

stephen

Reply
tikhonj  5 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.

  • prabhanjana_c  20 minutes ago

    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