This is very good - I have found that well-designed progressive disclosure systems like this tend to be far more effective and performant than cookie-cutter semantic / encoding-based RAG systems. Agents seem to love tables of contents.
Show HN: Treedocs: Documentation that automatically checks for staleness
11–20 of 22 posts
Re: Show HN: Treedocs: Documentation that automatically checks for staleness
#12This is very good - I have found that well-designed progressive disclosure systems like this tend to be far more effective and performant than cookie-cutter semantic / encoding-based RAG systems. Agents seem to love tables of contents.
It definitely feels more correct from a first principles perspective. It always seemed crazy that we often just throw a bunch of data at an LLM and go figure it out. It's filled with irrelevant junk. That would slow us down so why wouldn't it slow down AI?
Though I will say it has been a challenge to get agents to reliably use tools like `treedocs explore`. They tend to default to using their built in tooling first or commands like grep. I'm still working on reliable prompts and skills that tell the agent when to use which approach.
Re: Show HN: Treedocs: Documentation that automatically checks for staleness
#13Maaan, this seems so great except it's MacOS only.
I only have a Mac to test on, but I am open to releasing on Linux or Windows if someone would help.
Re: Show HN: Treedocs: Documentation that automatically checks for staleness
#14Hi HN, I built treedocs, a CLI that shows a tree of your file structure, side-by-side with docs. The idea is simple: your filesystem already tells you what exists, but not what each path is for. treedocs mirrors the file tree into a treedocs.yaml file and lets you define short descriptions, references, and links to files and folders. It can then render that back as a documented tree, detect drift when files move or d…
The question is who maintains it. I think, LLM is the only practical option. In my agent rules, I tell it to maintain INDEX.md on each level. That takes 1 line of instruction and starting with an example file. Then, it self-maintains.
In practice, the LLM, treedocs and I all work together to maintain it. treedocs finds missing and extra paths, and missing descriptions. The LLM writes descriptions. git makes sure I never forget to run treedocs sync. And I always have the ability to easily correct incorrect descriptions by the LLM, or add my own special instructions.
Sure the LLM can do all of that but it's a waste of a lot of tokens, and in my experience it often makes incorrect assumptions or doesn't realize certain details.
Re: Show HN: Treedocs: Documentation that automatically checks for staleness
#15Hi HN, I built treedocs, a CLI that shows a tree of your file structure, side-by-side with docs. The idea is simple: your filesystem already tells you what exists, but not what each path is for. treedocs mirrors the file tree into a treedocs.yaml file and lets you define short descriptions, references, and links to files and folders. It can then render that back as a documented tree, detect drift when files move or d…
This is lovely! I'd done something similar in my own setup. I'm curious what your experience has been with fork/merge – why a monolithic file rather than something more diffuse?
treedocs already has the ability to read multiple treedocs.yaml files. (I should probably document this better.) treedocs.yaml files can be "nested". So you would have one at the top of your repo, and then you could optionally have one or more in subdirectories. Then your top treedocs.yaml is responsible for the repo, but the subdirectory treedocs.yaml files are responsible for their own subdirectory. The idea is that you might have situations where you install a dependency and it clones a subdirectory. Well that subdirectory could just define its own treedocs.yaml.
So it doesn't have to be monolithic.
Re: Show HN: Treedocs: Documentation that automatically checks for staleness
#16Why is @DandyLyons' comment flagged and dead? Like ... what's wrong with what he posted? I've seen thousands of Show HNs here, for like a decade. Very similar to this. What rule did he break?
Idk. I did make some edits right after posting (just rewording stuff). Maybe the forum didn't like that?
Re: Show HN: Treedocs: Documentation that automatically checks for staleness
#17I made a similar kind of tool [0] to scratch this itch too. Hashes all your files and adds a short llm summary for each one so Claude/Codex can quickly explore rather than load all those files into context.
Re: Show HN: Treedocs: Documentation that automatically checks for staleness
#18I made a similar kind of tool [0] to scratch this itch too. Hashes all your files and adds a short llm summary for each one so Claude/Codex can quickly explore rather than load all those files into context. [0] https://github.com/tristanmatthias/llmdoc
Starred
Re: Show HN: Treedocs: Documentation that automatically checks for staleness
#19Why is @DandyLyons' comment flagged and dead? Like ... what's wrong with what he posted? I've seen thousands of Show HNs here, for like a decade. Very similar to this. What rule did he break?
I believe HN has some automations now that flag posts that look like they were LLM generated. I got caught out by that recently (in a post that wasn't fully LLM generated but quoted a line that probably was.)
You can email the mods and they'll fix it.