Is AI-Generated README Ruining Open Source Projects?

Recently, a Reddit post ranting about "atrocious READMEs in vibe coded projects" struck a chord with many. The poster bluntly pointed out that more and more projects—especially those "vibe coding" projects generated with AI assistance—are turning their READMEs into marketing copy, full of that unmistakable AI-generated flavor. This not only makes projects feel bloated but also turns otherwise excellent open source work into something hard to read.

The "Marketing Tone" of READMEs Is Running Rampant

The poster believes this problem has become very serious. Many project READMEs no longer aim for conciseness and clarity but instead adopt a "marketing" style—which, of course, is also AI-generated, and Claude in particular loves this tone. The author complains: "It should be concise, not stuffed with word salad." Even more absurd is that these READMEs always seem to assume the reader is a toddler touching a computer for the first time, eager to break down and explain every detail.

This style of writing is not only verbose but also carries a hidden underestimation of the reader's intelligence. Readers in the open source community are mostly developers—they need to quickly understand what the project does, how to install it, and key configuration—not to be treated as novices who need hand-holding.

vibe coding is a term coined by Andrej Karpathy in early 2025 that quickly went viral. It refers to a programming approach where developers mainly describe their intent to large models in natural language and let AI generate the vast majority of the code, with humans only steering direction and validating results. Its hallmarks are extremely fast onboarding and very short iteration cycles, but the output often carries a distinct "AI default style"—documentation especially. Related to this is the vibe coded project: such projects often go from idea to a runnable repository within days, with authors focusing their energy on features and typically keeping the model-generated README draft as-is without manual trimming—so marketing tone, over-explanation, and word salad all get carried into the open source community.

A Typical "Word Salad" Case

To illustrate the problem, the poster gives an example. A project's README, when describing "running locally," says:

"Runs locally: No cloud, no servers, no API keys, zero network calls. It parses your files right on your CPU, writes its cache to your local disk, and leaves the internet completely out of the equation"

The poster retorts: "This is just padding the word count!" Something that could be stated in one sentence—"Runs locally and is fully offline (caches data in %LOCALAPPDATA%\projectname)"—instead piles up a bunch of synonymous short sentences, using as many words as possible to convey as little information as possible. This style looks detailed but is actually hollow, and readers finish it feeling they've wasted their time.

Word salad was originally a psychological term referring to speech that is grammatically fluent but semantically empty and lacking in information. It has since been widely borrowed to describe text that piles up synonyms, parallel clauses, and decorative phrases while adding almost no new information. A practical criterion for judging whether a piece of technical documentation is word salad is "information density": if you delete the synonymous repetition from the sentences, does the remaining information stay almost unchanged? In the local-running description above, deleting any several items from "no cloud, no servers, no API keys, zero network calls" leaves the reader with exactly the same information—a classic symptom.

The Problem Is Widespread, Even in Showcase Threads

More worrying is that this phenomenon is not an isolated case. The poster suggests browsing the README of every other repo in the pinned "Show us what youve created" thread, and you'll find plenty of projects suffering from the same affliction. These projects themselves may be excellent, but poor documentation becomes an unnecessary barrier, driving readers away with lengthy text before they even understand the project.

Why Does AI Favor This Style?

Looking at the mechanics of AI-generated text, this "marketing tone" actually has traceable causes. During training, large language models absorb massive amounts of product copy, marketing pages, and tutorial content, and they tend to generate "safe" and "comprehensive" statements to ensure coverage of all possible scenarios. Thus, parallel clauses like "No cloud, no servers, no API keys, zero network calls" become the default output—it covers everything but ignores that human readers really need condensed information.

Additionally, AI often lacks the ability to judge the reader's background. It doesn't know whether it's addressing a senior developer or a beginner, so it has to write in the most conservative way (i.e., talking to a toddler). This "over-explanation" may work in marketing copy, but in technical documentation it only backfires.

The training objectives of large language models determine their tendency to generate "high-probability, comprehensive" text. During pretraining, models absorb massive amounts of product landing pages, marketing copy, and beginner tutorials—corpora that already favor parallelism, promise-style statements, and exhaustive enumeration; during alignment, models are further rewarded for being "helpful, thorough, and friendly in tone," so the default output is often a safe but verbose version. Moreover, the model cannot know the reader's technical level, so it has to write under the most conservative assumptions—this is the mechanistic reason for the "talking to a toddler" tone in technical documentation. Understanding this helps treat AI output as a draft rather than a final version.

How to Write a README That Doesn't Annoy People?

The poster's appeal is simple: hope this trend changes soon and doesn't become the default. For developers, avoiding an overly AI-flavored README isn't hard. First, clarify the core goals of a README: tell readers what the project is, how to use it, and what key configuration it has. Second, cut all decorative and repetitive short sentences, expressing things with the most direct combinations of verbs and nouns. Finally, remember that readers are developers—they don't need to be coaxed, only respected.

If you must use AI-assisted writing, consider manually trimming it after generation, deleting the "word salad." After all, a good README should be as clean and sharp as code, not as rambling as an advertisement.

The classic README structure can serve as a reference when trimming: a one-sentence project positioning, a minimal runnable example, installation and dependencies, key configuration items, FAQs, and license. The industry-cited "5-minute test" is also practical—can a new reader get it running and understand the project's purpose within five minutes? When writing, follow the order of "example first, explanation later," replacing descriptive paragraphs with copyable command blocks and short sentences; for details that truly need elaboration, put them in the docs/ directory or a Wiki, keeping the README as a lightweight entry page.

One-line Summary

AI-generated READMEs are full of marketing tone and word salad, dragging down excellent open source projects.

Paragraph Summary

Starting from a Reddit post ranting about "atrocious READMEs in vibe coded projects," the article points out that more and more AI-assisted projects turn their READMEs into marketing copy: piling up synonymous short sentences, over-explaining, and treating developer readers like toddlers touching a computer for the first time. The author uses a "running locally" example to show what "word salad" means—something that could be said in one sentence is expanded into five parallel short sentences. The article analyzes that this style stems from marketing corpora in large model training data and alignment objectives, as well as the model's inability to judge reader background, and offers improvement suggestions: clarify README goals, cut decorative content, manually trim AI-generated text, and make documentation as clean and sharp as code.