AI has quietly slipped into our daily developer workflows. It writes code, generates tests, summarises pull requests, and now more than ever writes...
For further actions, you may consider blocking this person and/or reporting abuse
We loved your post so we shared it on social.
Keep up the great work!
This is great! Thanks @sloan
Wow, this is such a thoughtful and insightful piece! I love how you balanced praising AI’s speed while highlighting the irreplaceable value of human context and clarity—your reflections really resonate with anyone who’s struggled with unread documentation.
Yes, I struggled quite a bit. I work as a software consultant, and a big part of my role is documenting systems so teams can be self-sufficient. I remember working on an identity component in AWS and having it documented with AI. Authentication is one of those areas where context evaporates quickly, so it wasn’t surprising that a couple of months later, I couldn’t understand what was actually supposed to be done :)
That’s such an honest and relatable experience, and it really highlights how tricky authentication and long-term context can be. It’s clear you put real care into making systems understandable for others, which is a skill many teams deeply benefit from.
Accurate. AI usually does well for other AI constructs to use in analysis etc. However for Humans to use with some understanding a human is best in the final say. Usability by humans can be best checked by humans. Yes it is slower but actually better.
First Draft AI, final say human. I have experienced this as in our company we do leverage AI heavily for analysis. The final take on the results of the analysis is and needs to be human.
I can totally relate to your concern, and thanks for putting it out!
Thank you!
The speed with which AI can generate texts is undoubtedly impressive. By analyzing trends and tendencies, it can accomplish in minutes what would often take humans much longer. However, this efficiency comes at a price: the language often loses its individuality and can become overly complex, polished, and somewhat lifeless.
Really well put. This nails the difference between documentation that exists and documentation that actually helps. Using AI for structure is great, but without a human pass it turns into verbose, forgettable text. The point about docs needing to survive time and explain tradeoffs really hit home. Speed ≠ clarity.
AI is great at producing text, but documentation definitely about shared understanding over time.
Definitely, these days, I rely on it to get started, mostly for the template or the document skeleton, because that part does take time. But I always proofread and strip out all the extra junk it tends to generate.
I use it to structure something I've written but I don't use it for the actual content. I really can't bear its output
Idea: feed a shortened version of this article to AI asking it to write a guideline for writing READMEs. Then ask to save it as custom slash command /update-readme globally. Now in every project you can write just /update-readme and have READMEs that should avoid problems you described here. Of course to get exactly where you want to get you need to do some iterations, telling it to avoid things that you notice in your test outputs until it gets it right. It's an art.
Nice idea. A slash command like this could help set some basic rules.
The tricky part, as you hinted, is iteration. AI tends to hallucinate and over-explain, which is exactly why a lot of READMEs get ignored in the first place. Without human judgment and pruning, even a good command can produce noisy docs.
So I see this working best as a starting point, not an autopilot. The human edit step is still the most important one.
Thanks for sharing this perspective.