Any hints what should I look at to avoid this?
I hope you like the concept of the ox at least ;)
If you think about how you speak in your native language, it probably has a certain rhythm of long and short sentences, with some "shallow" sentences that just say one thing, but then sentences that nest other clauses that could be whole sentence of their own, and then a hanging sentence fragment that makes sense in context, etc. As far as I know, every spoken language, English or otherwise, looks like that when humans are writing it.
The human mind's "buffer of verbalization" seems to be quite short, basically around one grammatical "clause" in size. So humans, when writing (or speaking) "off the cuff", generally only try to keep "a non-verbalized concept of what they want to say" plus "the verbal pattern for the current grammatical clause" buffered in their heads. A human speaker will only start deciding how to glue the next clause onto the current clause—whether to make it a new sentence, or use some preposition or conjunction, or to "verbally backtrack" / "interrupt themselves" to add detail "before" what they said—when they get to near the end of speaking/writing a clause. Much of the "reason" for the grammars of spoken languages to be structured the way they are, is to allow for this kind of narrow-buffered "streaming" composition.
Human written language can look different when someone has sat down and taken this "off the cuff" writing as a first draft, and intensively edited and rearranged and polished it. But the result of doing this still usually retains a lot of the original positive qualities of the "off the cuff" writing that went in. (Editors are told to not over-edit, because doing so will remove the "author's voice" from the writing. The particular grammatical gymnastics a speaker/writer uses to connect their thoughts can be a large part of this "author's voice.")
LLMs, despite "streaming" in a much more literal sense than humans do, seem to avoid "off the cuff" generation of successive grammatical clauses using "whatever grammatical glue works to get to the next thought." Instead, they seem to have been forced by their training into favoring particular sentence structures that allow them to never end up needing to reach for artful just-in-time grammatical connections in the first place. Mainly, they like using sequences of short sentences that each say exactly one thing.
(I hypothesize they like these forms because, in some internal layer of the model, these sentences can be represented all-at-once as plans, and so can be emitted in a token order that results in the "polished, edited writing" style rather than the "off-the-cuff speaking" style. Much of the base-model training dataset — the stuff that made the model understand language and writing at all — came from polished, edited writing rather than casual/conversational writing. However much the model is trained to adopt a casual style, it's doing so on top of a language-generation "module" that tries to plan entire sentences rather than streaming clauses.)
I know of no other way, because there are lots of technically grammatically correct ways to say things in English, but sounds awkward to a native speaker. You can’t know really on your own.
It always comes out that the learner speant to long with or only used one source for their learning.
As a counter-example, chinese ESL learners will often look for "American Business English" because our office speak is different enough from common speach and that is their intended use case for the language they're learning. They don't want to sound like they're announcing the news or acting in a movie, they want to sound like business professionals.
I use HTMX and like it so I might have read if it didn’t look like spam post.
Good luck with your project. Your English fluency is fine.
Anyhow, thanks for commenting - will try to improve for next time
Thanks!
PS: send your bank details via email, not here in public ;)
Definitely the fact that I have ai makes it more fesable for me to actually publish something rather than spednign years on copy I can spend time on code and outsource copy
Would you have any hints what to avoid for „next time”? Should I just make this absurdly small and make much less polished approach even for this kind of project? Honest question. Will try to work on anything you suggest <3
This is a great example of one of the current failure modes of coding agents (which were almost certainly used here): the creator of this project probably described the project in these terms to the agent. Something like:
> I want to make a Javascript library that works like Htmx or Datastar SSE, enabling a web developer to add well-known behaviors to a page just by adding HTML attributes. This library will be for the cases those libraries don't cover: triggering purely-local state changes in the state of [elements? web components? not sure]; where because these state changes get persisted to the DOM in some way or another, they are visible to, the state these behavior-attributes mutate can be referenced by Htmx/Datastar/etc in their behavior-attribute DSLs.
Then, either because the agent is already briefed in these terms — or because the agent has then gone on to write all the code for this library in the same conversation, and so has that code in its context — the result is that the agent, when it moves on to the "generate docs and README" step, treats all this as assumed shared context for those docs, since (from the agent's perspective) the docs and README exist "in" the conversation "downstream" of the project brief and code; and, from its original base-model training, the model knows that things introduced early in a conversation shouldn't be re-introduced later on in the same conversation, but rather should be succinctly referenced.
(My hypothesis, that I haven't yet tested, is that you can work around this flaw by starting a fresh conversation before asking the model to write docs. The model should see info that enters the context through e.g. "read a file" tool-call responses differently than it sees things you or it "say", not treating that info as "real" conversation turns but more like e.g. source-code excerpts in a blog post, where the learned base-model expectation would be that everything that appears in the excerpted figure will be re-explained in plain language in following prose.)
But, of course, this is still a flaw in current models, and the "right" solution is still for the model providers to train models to be able to conceptualize of multiple "conversational reference graphs" co-occurring within the context, and compartmentalize linguistic/semantic referencing on a per-graph basis; such that top-level prose and inline code excerpted for explanation both exist in the default "internal" reference graph, while code and docs generated to be written into a codebase through tool-calls exist in a separate "external" reference graph.
Maybe I should try to approach docs in non-htmx / Datastar user context - will think about it