Discussion
Your Docs Directory Is Doomed
holliplex: I would describe myself as pretty AI-positive in software engineering, and even in technical writing, but something about seeing diagrams that are clearly generated by Nano Banana Pro immediately makes me stop reading. Weird!
soapdog: Well, maybe I want my docs folder to be useful for humans checking my code and don't care about LLMs at all..
bartvk: That's not the only thing clearly generated. "Some looming issues", "some thorny issues", it's full of these weird AI sayings. The whole thing feels weirdly written.
soulofmischief: The constant changing of tense in this article makes it very hard to read.
rokkamokka: The blog reads like an advertisement for some product that doesn't exist (yet?). It seems rough to store, access and accurately update this context-code mapping
iamcalledrob: Same.I think I've unintentionally trained myself to notice (and tune out) both AI illustrations and AI writing.At a deep instinctual level, knowing that someone hasn't spent much time or effort creating the content makes me not want to reciprocate with time or effort.I've realised that my brain literally tunes out AI illustrations, much as it does with ad banners.Perhaps since they're easy to generate, I encounter illustration more -- it's no longer a signal of quality.
outime: To me, the something in this case is the mangled text and the weird "lighting" in some of the icons. Not the worst I've seen but it definitely puts you off.
postit: Im from the opinion that not only for AI agents but detailed development docs (ADRs, Specs …) should live alongside each package.High level and user docs in /docs
Toutouxc: I feel like the article either doesn't really contain any information, or is describing the concept of "code comments" after being translated through 35 languages.
BoredPositron: Depends making an ascii diagram or one in cali and adding flair with nano seems fine. You do the logic nano adds the flavor.
CharlieDigital: Here's an easier solution that actually works, gives any agent FREE long term memory (platform agnostic and zero infrastructure!), always accurate context that is self-maintained by the LLM.Use the idiomatic comments for your language.Here is a snippet of our prompt for C# (and similar one for TS): - Use idiomatic C# code comments when writing public methods and properties - `<summary>` concise description of the method or property - `<remarks>` the "why"; provide domain or business context, chain of thought, and reasoning; mention related methods, types, and files - `<param>` document any known constraints on inputs, special handling, etc. - `<return>` note the expected return value - `<example>` provide a brief example of correct usage - Use inline comments sparingly where it adds clarity to complex code - Update comments as you modify the code; ensure they are consistent with the intent of the code What happens: when the LLM stumbles upon this code in the future, it reads the comments and basically "re-hydrates" some past state into context. The `<remarks>` one is doing heavy lifting here because it is asked to provide its train of thought and mention related artifacts (future LLM knows where else to look).You already know the agents are going to read your code again when it gathers context so just leave the instructions and comments inline.The LLM is very good at keeping these up-to-date on refactors (we are still doing human code reviews) and a bonus is that it makes it very easy to review the code to see why the LLM generated some function or property because the reasoning is right there for the human as well.
qntmfred: I wish IDEs had better support for quick toggling the display of comments. You make a good point about it making sense for the docs to live alongside the code, I just don't usually want to see giant comment blocks everywhere while I'm operating in a codebase.
CharlieDigital: JetBrains Rider has this as does VS Code: CMD+K, CMD+/ to fold, CMD+K, CMD+J to unfold.
chewbacha: Common AI blog posts that seem generated:1. State problem created by AI2. Provide simple solution3. State it cannot work and AI won’t help4. Describe another way to solve for AI with more workThis feels like at least the third blog I’ve read that follow this pattern and have the hallmarks of generated text.People are playing LLM slot machine for engagement blogs.
lelanthran: > The whole thing feels weirdly writtenI keep repeating this: AI written prose lives in an uncanney valley that is both clearly grammatically correct but still weirdly off.Why do we think that the AI generated code is any better?I described AI-generated code as feeling very "alien" to me, but I'm not sure that that is the correct term.
