Re: README.md files per directory

On Mon, May 4, 2026 at 8:35 AM Olivier Cochard-Labbé <[email protected]>
wrote:

>
> On Thu, Apr 16, 2026 at 8:34 PM Farhan Khan <[email protected]> wrote:
>
>> Any thoughts on having README.md files in each directory? It would
>> describe what the code was for, the maintainer, things that might help a
>> would-be developer, status, TODOs, etc.
>>
>> There's some code I recently found that I had no idea what it was until I
>> asked AI. It might also be useful in public code displayers, such as
>> Github, Gitea, etc.
>>
>>
>>
> I’ve tried, as a side project, to self-generate such README.md using LLM.
> But as a full newbie in this domain, I’m fighting very hard to avoid all
> the LLM hallucinations.
> The idea was to re-generate the documentation every-week (because I’m
> running it on a Framework Desktop with a local-model to be self sufficient,
> so it took about 12 hours to generate).
>
> And example of by this PoC (bad quality) documentation generated is here:
> https://github.com/ocochard/freebsd-src/blob/AI-doc/README.all-chapters.md
>

So I took a look at the areas I'm a domain expert on (or think I am) and
this is a good first approximation. However, there's a lot of non-sequitor
asides that distrupt the flow. There's almost right assertions. There's
improper focus on what to document.

So while not ready for prime time, it is impressive what it's been able to
come up with. I wouldn't rely on the docs to understand how things work
entirely, but it does get one close. It's the almost that's going to trip
you up.

Warner