Date: Mon, 4 May 2026 09:26:04 -0600 From: Warner Losh <imp@bsdimp.com> To: =?UTF-8?Q?Olivier_Cochard=2DLabb=C3=A9?= <olivier@freebsd.org> Cc: Farhan Khan <farhan@farhan.codes>, "O'Connor, Daniel via freebsd-hackers" <freebsd-hackers@freebsd.org> Subject: Re: README.md files per directory Message-ID: <CANCZdfptXDfY0_Dz7npKp8hSuG=H2yUGdtPGvAuDhCUjS84Jhw@mail.gmail.com> In-Reply-To: <CA%2Bq%2BTcoj=1CJTC-R7qXnhO5MK7Y01Tq1ZUA4FAv%2BgtoQxOzseQ@mail.gmail.com> References: <23bcac37-d280-47e1-88da-542df544a6cf@app.fastmail.com> <CA%2Bq%2BTcoj=1CJTC-R7qXnhO5MK7Y01Tq1ZUA4FAv%2BgtoQxOzseQ@mail.gmail.com>
index | next in thread | previous in thread | raw e-mail
[-- Attachment #1 --] On Mon, May 4, 2026 at 8:35 AM Olivier Cochard-Labbé <olivier@freebsd.org> wrote: > > On Thu, Apr 16, 2026 at 8:34 PM Farhan Khan <farhan@farhan.codes> 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 [-- Attachment #2 --] <div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote gmail_quote_container"><div dir="ltr" class="gmail_attr">On Mon, May 4, 2026 at 8:35 AM Olivier Cochard-Labbé <<a href="mailto:olivier@freebsd.org">olivier@freebsd.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div dir="ltr"><div style="font-family:"courier new",monospace"><br></div></div><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Apr 16, 2026 at 8:34 PM Farhan Khan <farhan@farhan.codes> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">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.<br> <br> 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.<br> <br><br></blockquote><div><br></div><div style="font-family:"courier new",monospace">I’ve tried, as a side project, to self-generate such README.md using LLM.</div><div style="font-family:"courier new",monospace">But as a full newbie in this domain, I’m fighting very hard to avoid all the LLM hallucinations.</div><div style="font-family:"courier new",monospace">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).</div><div style="font-family:"courier new",monospace"><br></div><div style="font-family:"courier new",monospace">And example of by this PoC (bad quality) documentation generated is here:<br><a href="https://github.com/ocochard/freebsd-src/blob/AI-doc/README.all-chapters.md" target="_blank">https://github.com/ocochard/freebsd-src/blob/AI-doc/README.all-chapters.md</a></div></div></div></blockquote><div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div>Warner</div></div></div>home | help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CANCZdfptXDfY0_Dz7npKp8hSuG=H2yUGdtPGvAuDhCUjS84Jhw>