10 ms·
> the documentation is poorly written (all LLM vendors seem to have an internal competition in writing confusing documentation). This is almost certainly becau
by lolinder 1y ago
> the documentation is poorly written (all LLM vendors seem to have an internal competition in writing confusing documentation).
This is almost certainly because they're all using LLMs to write the documentation, which is still a very bad idea. The MCP spec [0] has LLM fingerprints all over it.
In fact, misusing LLMs to build a spec is much worse than misusing them to avoid writing good docs because when it comes to specifications and RFCs the process of writing the spec is half the point. You're not just trying to get a reasonable output document at the end (which they didn't get anyway—just try reading it!), you're trying to figure out all the ways your current thinking is flawed, inadequate, and incomplete. You're reading it critically and identifying edge cases and massaging the spec until it answers every question that the humans designing the spec and the community surrounding it have.
Which means in the end the biggest tell that the MCP spec is the product of LLMs isn't that it's somewhat incoherent or that it's composed entirely of bullet lists or that it has that uniquely bland style: it's that it shows every sign of having had very little human thought put into it relative to what we'd expect from a major specification.
[0] https://modelcontextprotocol.io/specification/2025-03-26 https://modelcontextprotocol.io/specification/2025-03-26
- clbrmbr 1y agoCertainly a shame if true, there are some really sharp folks at Anthropic and this is an important building block in the emerging ecosystem.
- teaearlgraycold 1y agoIn my experience AI startups are AI maximalists. They use AI for everything they can. AI meeting summarizations, AI search (Perplexity), AI to write code and contracts, AI to perform SEO, AI to recruit candidates, etc. So I 100% believe they would use AI to write specs.
- runlaszlorun 1y agoSeems like many are dreading our near future. Not I, I can't wait to see how this all plays out...
- whatever1 1y agoSo many bullet points in the documentation!
- jes5199 1y agosomeone is going to write an MCP adaptor that lets Claude use OpenAPI and then we can forget that MCP was a thing
- otabdeveloper4 1y agoThis. Endure a couple months and this madness ends.
- cruffle_duffle 1y agoHow would that even work?
- DonHopkins 1y agoSouth Park explored that question: https://www.youtube.com/watch?v=sbCj0i8WQA0 https://www.youtube.com/watch?v=sbCj0i8WQA0
- jes5199 1y agonew MCP tool: make-curl-request, headers, payload
- benatkin 1y agoThe DeepSeek documentation seems to be better. It looks to be quickly thrown together but not bad. I’m not sure what that says about LLMs writing documentation.
- ljm 1y agoSometimes I wonder if I have ADHD or if it's induced by the content, because I can spend hours soaking up interesting literature and putting my weird thoughts down onto paper but I can barely make it a few words through LLM-driven drivel. It's crazy seeing bots posting AITA rage bait on Reddit that always follows the same pattern: some inter-personal conflict that escalates to a wider group: "I told my husband I wasn't into face-sitting and now all my colleagues are saying I should sit on his face to keep the peace." That is one thing but using the same LLM to drive your tech specs, knowing it can say a whole lot of shit the 'author' isn't aware of, because they're illiterate and that is fucking normal... is worrying.
- stuaxo 1y agoYeah it's unreadable for me. There's been a trend to post LLM slop about tech subjects and they anger me - I don't know why someone wanted to waste people's time like that. Even worse - I've come across an AI slop site that masquerades as dev information, with just plain wrong information.
- DonHopkins 1y agoI let the domain "micropolisonline.com" expire, which I was using for the old OpenLaszlo/Flash Python/SWIG/C++ client/server based version of open source SimCity, and somebody took it over and replaced it with AI generated claptrap, stealing a lot of my own and other's images without any credit. It even promises the source code, but doesn't actually link to it, just has promises and placeholders. It totally misrepresents what Micropolis is, which was based on the original SimCity classic, and confuses it with all the subsequent versions of SimCity and other made-up stuff. And it never mentions the GPL-3 license, EA's license and restrictions on the use of their SimCity trademark, or Micropolis's license to use their trademark. I have no idea what the point of it is. https://micropolisonline.com/ https://micropolisonline.com/ https://micropolisonline.com/source-code/ https://micropolisonline.com/source-code/ >How to Access the Source Code: For those eager to explore the Micropolis Online Source Code, it is available on our dedicated GitHub repository. Visit [Link] to access the repository, where you can browse the code, contribute to ongoing projects, or initiate your own. The source code is actually not at [Link] but at: https://github.com/SimHacker/MicropolisCore https://github.com/SimHacker/MicropolisCore Not even so much as a link to the my demo! https://www.youtube.com/watch?v=8snnqQSI0GE https://www.youtube.com/watch?v=8snnqQSI0GE They could be in some legal jepordy since they didn't mention or link to the Micropolis GPL License or the Micropolis Public Name License, which they may be violating. https://github.com/SimHacker/MicropolisCore/blob/main/MicropolisGPLLicenseNotice.md https://github.com/SimHacker/MicropolisCore/blob/main/Microp... https://github.com/SimHacker/MicropolisCore/blob/main/MicropolisPublicNameLicense.md https://github.com/SimHacker/MicropolisCore/blob/main/Microp... The have a "Meet the Team" page that mentions nobody, just hand waves about "we" and the community. They couldn't even bother to generate generic looking fake profiles of non-existent people. Suffice it to say I never heard back from anyone after using the "Contact Us" page. They even have a cute little Terms and Conditions page with their very own license, which doesn't allow anyone to do to them what they did to me, and is not particularly GPL-v3 compatible: https://micropolisonline.com/terms-conditions/ https://micropolisonline.com/terms-conditions/ >License to Use Micropolis Online >Unless otherwise stated, Micropolis Online and/or its licensors own the intellectual property rights for all material on Micropolis Online. All intellectual property rights are reserved. You may view and/or print pages from micropolisonline.com for your own personal use subject to restrictions set in these terms and conditions. >You must not: >Republish material from micropolisonline.com Sell, rent, or sub-license material from micropolisonline.com Reproduce, duplicate, or copy material from micropolisonline.com They also claim all rights to all user created content: >By displaying Your Content, you grant Micropolis Online a non-exclusive, worldwide irrevocable, sub-licensable license to use, reproduce, adapt, publish, translate, and distribute it in any and all media. Kind of ironic for an LLM to go around stealing people's content, then telling them that not only can't anyone copy it back, but it owns the rights to everything anyone else may contribute in the future.
- jerf 1y agoIt had not occurred to me that the AI coding vendors are basically positively motivated to themselves produce code that is not documented. They want code that is comprehensible to AIs but actively not comprehensible to humans. Then you need their AIs to manipulate it. AI code as the biggest "lock you in the box" in programming history. That takes rather a lot of the luster out of it.... They'd better be right that they can get to the point that they can fully replace programmers in about two years, otherwise following this siren song will, well, demonstrate why I chose "siren song" as my metaphor. If AI code produces big piles of code that are simply incomprehensible to humans, but then the AIs can't handle it either, they'll crash out their own market by the rather disgusting mechanism of killing all their customers, precisely because the customers consumed their service.
- walterbell 1y agoSelf Alignment™
- never_inline 1y agoTo be honest I don't think they have any plans either.
- ComplexSystems 1y agoDeepSeek's documentation has a different problem, which is that there are spelling errors and weird grammatical constructions everywhere: "DeepSeek API does NOT constrain user's rate limit. We will try out best to serve every request. However, please note that when our servers are under high traffic pressure, your requests may take some time to receive a response from the server. During this period, your HTTP request will remain connected, and you may continuously receive contents in the following formats..." The documentation is still mostly easy to read, so it doesn't *really" matter, but I always thought this was bizarre. I mean, I get the language barrier reading manuals from Chinese products off of Amazon or whatever, but this is a company that does nothing but work with language all day long, and even at one point had the world's leading English-speaking language model. Shouldn't they be able to produce professional-looking documentation without spelling and grammatical errors?
- comradesmith 1y agoWhat’s the problem? Can you point out a specific thing you would change from that quote?
- albert_e 1y agoMaybe the first sentence? I am guessing they meant "DeepSeek API does not enforce any rate limit on users." would be more appropriate. _Constraining the rate 'limit'_ seems like incorrect usage - but it is an a easy mistake to make in a first draft. Review should have caught it.
- lolinder 1y agoAre you a native English speaker? "does NOT constrain user's rate limit" should be "does NOT rate limit incoming requests" or similar. "We will try out best" should be "our best". "when our servers are under high traffic pressure" is at least grammatical, but it's awkward. Normally you'd say "when our servers are dealing with high load" or something similar. "your requests may take some time to receive a response from the server" is again grammatical but also awkward. "Our response times may be slower" would be more natural. The last sentence is also awkward but the whole thing would need to be restructured, which is too much for an HN comment. Basically: everything about this screams English as a second language. Which does mean that it's unlikely to have been LLM generated, because from what I've seen DeepSeek itself does a pretty good job with English!
- glimps 1y agoI get the distinct feeling the spec was created by llm too. As with the doc, every evidence hints at it. Makes great IPO to tell investor most tour product are already created be averaging out the most likely outcome
- meander_water 1y agoI can't say whether the original spec was written with AI assistance, but having a cursory look through the commit history [0] it doesn't look like they're just blatantly auto-generating the docs. The git history indicates that they do think about the spec and manually update the docs as the spec changes. [0] https://github.com/modelcontextprotocol/modelcontextprotocol/commits/main/ https://github.com/modelcontextprotocol/modelcontextprotocol...
- never_inline 1y agoI don't write perfect English. Far from it. But I'd prefer broken English any day over default LLM verbiage. It seems so unnatural and facetitious. I always have this in my prompts: "Be succinct and use simple English sentences".