Generic Documentation

[devicemxl]

"Vibe Docs"

• General Architecture
• Discovery of some hidden layers in the project:

1. es01-LAYER1-INFRA.md — Infrastructure (1,156 lines)
2. es02-LAYER2-MEMORY-SYNCHRONIZATION.md — Memory & Sync (849 lines)
3. es03-LAYER3-PERSISTENCIA-TRANSACTION.md — Persistence & Transactions (1,547 lines)
4. es04-LAYER4-DATA-STRUCTURES.md — Data Structures (1,823 lines)
5. es05-LAYER5-INDEXING.md — Indexing (1,365 lines)
6. es06-LAYER6-DATA-MODEL.md — Data Model (1,471 lines)
7. es07-LAYER-USER-API.md — API User (948 lines)

• Written in Spanish and English

[xach]

This is not very good compared to reading the code.

[xach]

It's also adding a ton of noise.

[gwangjinkim]

@xach What do you think then would be better to document? What would be more helpful for the users? Let's think about this.

I think vibecoding/context engineering is a great chance for the Lisp community to experience a revival.

More people (or LLMs) could contribute to the ecosystem. And maybe finally Common Lisp and other Lisps could thrive as an ecosystem.

And I am always curious what the more experienced ones (like you) think what is important when using the modern approach.

[xach]

Something that adds high-level information, examples, etc. Going through and documenting the lowest levels with low-quality information that simply recaps the code is not useful.

[gwangjinkim]

@xach True - and something that captures somehow the intend of the code - or decisions - the why - and not just describes 1:1 what it does (low level as you say).

[vindarel]

Let's recall that gwangjinkim generated documentation too, see #3 (comment) => https://github.com/gwangjinkim/vivace-graph-v3/blob/master/vivace-graph-v3-doc.org (which I found useful, I didn't read this one, too long!)