From nobody Mon May 4 15:26:04 2026 X-Original-To: freebsd-hackers@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4g8QTl02qFz6bPZ3 for ; Mon, 04 May 2026 15:26:19 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Received: from mail-pl1-x62c.google.com (mail-pl1-x62c.google.com [IPv6:2607:f8b0:4864:20::62c]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "smtp.gmail.com", Issuer "WR4" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4g8QTk4qR5z3d84 for ; Mon, 04 May 2026 15:26:18 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Authentication-Results: mx1.freebsd.org; none Received: by mail-pl1-x62c.google.com with SMTP id d9443c01a7336-2ad617d5b80so25317525ad.1 for ; Mon, 04 May 2026 08:26:18 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1777908376; cv=none; d=google.com; s=arc-20240605; b=Lm5Rqq3pWz8mSqB6s02yuIu9uFG5BusUnEpJ8ENYZc4UKs/5TGS8GJzF7bt4hix6VW NXRUJP80BO8aAu4UZBqHW87+xsyqiHqZHl3+pNFLyhW0iRaoo5fGIJ1hDdoxMu8e02vr dbFY8G8msXCS1YGWBTgL3aqf13FLeyj7KWxO53nhG457AfkBeq7ijjP33cMcpsAHufLl l0lYMJyHqpZ1mY5FebtyBtW0GxluB20DdpLTnP/ksE5tUuLXQxYQi+qCgwt3V8yDoTSX HWie33NhmK93zOoxB3UsHXyLVOP2csAedwBG9krqyJuBYg7PHeAUtV5mOCTuDdLHtjk+ P3/w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20240605; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:dkim-signature; bh=XkyboB5LrBw3kFBxX/7A4iuBz+RRRUnvSPGvtVCAVYU=; fh=XqcjyxecvZriRTwRqxvHwXaoTtD8IF2oZBCTAGEWsP8=; b=HfR1pVDqNFd3QE7MkYM3YOaIEfvBjo/Z0Ga2Hz+45wG5g6VRxhh+urOW9Ht+n1sUCv DxFDHH4D8Buv9+i30ihVs1eIiVt8TiSK+kzz6ZR7iN5DzVxUNhi1ZcfM5QmkNMWB/ueV fOtVTJsYZTz2JJbkTqTKqub2vYoB0NxwyI22A4zcV/mA4m3vFll90UZve3nDrz9vQySj yfiIv7layaVtmi6Y75gbinCrnqRLG9YEUlioPqzJVIxeImJaTIA8kPu8YWBK5qg/3hZE Sdx6Bb/QPymccrWNMWc6YIOo4P8k0h/hQRYLvctKkKyRRjMDJaj3W/QWWPhskmd8VOiT W6tA==; darn=freebsd.org ARC-Authentication-Results: i=1; mx.google.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bsdimp-com.20251104.gappssmtp.com; s=20251104; t=1777908376; x=1778513176; darn=freebsd.org; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=XkyboB5LrBw3kFBxX/7A4iuBz+RRRUnvSPGvtVCAVYU=; b=joGYQeX3XoxN61sTu1PT88Owb0LAxLoL7pMa5lmzOmY5FkcS1NCDYqPDB9gkrsRsNk szNaevs2gnW80+1vuxAznwBUz33ypjtcAm3Y06o0r8sJwwm/65PbYQofSozCO/KkN7rC pBqZs/oaddI1nFYD/yUpmLP0ntpLqZc3e3NhEN1skVvbI6Vqy1xBVUOcpK2zrSegFUxA wPC/ZJeVFwgjc+wq/SxRvVV64JNoVUsONB9U6PrAhwfoDfI0NdqQ8l8bjJbAZU7/6tiy 1hTp/2c3Dco8s2DM96kEEbf6KdAJC36rQNVsozdqvso1xv6bRp7wtLIO5bkX0wPJEgWx egVA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1777908376; x=1778513176; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-gg:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=XkyboB5LrBw3kFBxX/7A4iuBz+RRRUnvSPGvtVCAVYU=; b=OfKM1YVwMpsS7EEoZ3ZpONH2tazW2LVrIvKyQvGRlj3iLWaeY9xnhnt6UJGW4fN6AR BZoDkAKdWN7MTI9vGRWwQwXwVTs2e03TtU9pvm2Snjdl9O/6miIUge3GBht0ZpkOvfek x9iJA15gw2Tjc9ga0TrPVYQzCBu88MH60gIA5xuDyL6Wc0jaMTfM7Vvn8nHiiSZ0Og4l y3PdcUe0t4f8U4uEBEIsNLS1bucG5tGme3ZKMTT/G3pKveZI0hyfqz9D3o9VDd3GLa5U XpXda3n7YcrxjP/WsHwGAMzKB9KLT1rR+1SBR0APC4w/KuzGD8NzO4OjcvDZqblbcr4G DHBQ== X-Forwarded-Encrypted: i=1; AFNElJ+RUCvyLpK774X/mNL6gRDtGbngoyEJZdrseW4dg9i9yrebYpVYrhX6aDzEjQF/XoKozgEuFdPJ14Bpbr12eS4=@freebsd.org X-Gm-Message-State: AOJu0YzqIqHfcsUWjud+ZuJWcrRPE+NZySCxZIE5Y7LrXqo81fyCxbf+ AmqcisQtgkLFvW5V/OgRp/Siamw+V/yEhSUkAWBE+eTXnNF4QLyiDrdQmDK8449ubKOwlrfo9rp LM7s/Hht5Md3H/H9183fNF98t5kGtITEC2hn6thEMZKIjAxnpG4X6/Xw= X-Gm-Gg: AeBDietW13wgJ857OglibYilPrYAIVg0s1NV6XXpZWKS8X/PSsrFqxgCM2UyZVwq6gS 8R/i2wWz6+0whbz9VM3OiOvnHoGUmr47HaARdBkypL96Zf0LYTg8ArG1nCham7hRjGuYL/ILD0R XCF1tHltsZjfXtyAeypGO2R9kGtdIvK3i8p72gXafyEUVX1yD8TLByn+5H6a1ddbr83SzuTDIWR Y/ZyNNYuBH0QItTei2daa4ZGc6OUJJBuTaiqT7+9HQrm2YHZrLgM2amFsAGkZQTIoqtF3ts9pcr /xTSddnXwX69/HeZ/w== X-Received: by 2002:a17:902:ebc2:b0:2b4:5c20:ec7 with SMTP id d9443c01a7336-2b9f28590bemr96417995ad.41.1777908376220; Mon, 04 May 2026 08:26:16 -0700 (PDT) List-Id: Technical discussions relating to FreeBSD List-Archive: https://lists.freebsd.org/archives/freebsd-hackers List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-freebsd-hackers@FreeBSD.org List-Id: List-Post: List-Help: List-Subscribe: List-Unsubscribe: List-Owner: Precedence: list MIME-Version: 1.0 References: <23bcac37-d280-47e1-88da-542df544a6cf@app.fastmail.com> In-Reply-To: From: Warner Losh Date: Mon, 4 May 2026 09:26:04 -0600 X-Gm-Features: AVHnY4If7nWrPmQdSkkfgl0074tH8F4jyX1VIGypzo7BhLQoe2pNyRc9-GByfn4 Message-ID: Subject: Re: README.md files per directory To: =?UTF-8?Q?Olivier_Cochard=2DLabb=C3=A9?= Cc: Farhan Khan , "O'Connor, Daniel via freebsd-hackers" Content-Type: multipart/alternative; boundary="00000000000035442c0650ff8d4c" X-Spamd-Result: default: False [-4.00 / 15.00]; REPLY(-4.00)[]; ASN(0.00)[asn:15169, ipnet:2607:f8b0::/32, country:US] X-Rspamd-Queue-Id: 4g8QTk4qR5z3d84 X-Spamd-Bar: ---- X-Rspamd-Pre-Result: action=no action; module=replies; Message is reply to one we originated --00000000000035442c0650ff8d4c Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable On Mon, May 4, 2026 at 8:35=E2=80=AFAM Olivier Cochard-Labb=C3=A9 wrote: > > On Thu, Apr 16, 2026 at 8:34=E2=80=AFPM Farhan Khan = 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=E2=80=99ve tried, as a side project, to self-generate such README.md us= ing LLM. > But as a full newbie in this domain, I=E2=80=99m fighting very hard to av= oid all > the LLM hallucinations. > The idea was to re-generate the documentation every-week (because I=E2=80= =99m > running it on a Framework Desktop with a local-model to be self sufficien= t, > 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.m= d > 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 --00000000000035442c0650ff8d4c Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable


On Mon, May 4, = 2026 at 8:35=E2=80=AFAM Olivier Cochard-Labb=C3=A9 <olivier@freebsd.org> wrote:

<= div class=3D"gmail_quote">
On Thu, Apr= 16, 2026 at 8:34=E2=80=AFPM 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, statu= s, 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 Git= hub, Gitea, etc.



I=E2=80=99ve tried, as a side project, to self-genera= te such README.md using LLM.
But as a full newbie in this domain, I=E2=80=99m fighti= ng very hard to avoid all the LLM hallucinations.
The=C2=A0idea was to re-generate t= he documentation every-week (because I=E2=80=99m running it on a Framework = Desktop with a local-model to be self sufficient, so it took about 12 hours= to generate).

https://github.com/ocochard/freebsd-src/b= lob/AI-doc/README.all-chapters.md
So I took a look at the areas I'm a domain expert on (or t= hink I am) and this is a good first approximation. However, there's a l= ot of non-sequitor asides that distrupt the flow. There's almost right = assertions. There's improper focus on what to document.

<= /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 h= ow things work entirely, but it does get one close. It's the almost tha= t's going to trip you up.

Warner
--00000000000035442c0650ff8d4c--