The References landing page is a very confusing landing page that could provide a lot better direction and context around what reference content exists on xrpl.org.
There are four top-level items, all with confusing names, and they aren't particularly representative of what people might want to do with the XRP Ledger:
rippled API Reference → most of the good stuff is buried in here. Transactions! Ledger data! The API methods that are most likely to persist into the future! I mean, there are a lot of regrettable inconsistencies in the rippled APIs but they're definitely the most fundamental bedrock of XRP Ledger programming—everything else is built on top of them, so they have to stick around.
It could make sense to split certain parts off as a "Protocol Reference" that's relevant to every language and interface, separate from the parts that are specific to calling WebSocket and JSON-RPC. Transactions and Ledger Data Formats are the most obvious ones but there are probably some more things that could/should be split off. There will always be some that don't cleanly fit into one or the other bucket though.
XRP-API → a REST interface built on top of rippled, which is another service you have to stand up independently, never really finished and now approaching one year since significant dev work was done on it. But it has an appealing name, so it's likely to draw people's attention away from the other stuff. The blurb for it is totally misleading and confusing (I'm actually not sure at the moment where it's getting that phrase. I think maybe it's inheriting it from the target? Oops.)
RippleAPI Reference → almost the exact same name as the first thing, but this one's a client library for JavaScript/TypeScript. That's confusing enough, but the actual documentation for this library is also a bit of a mess; it's all in one page, there's no concise list/table of methods, there are a bunch of older interfaces and data structures that are probably considered deprecated to some degree or other, and so on. (The library itself is about due for a breaking-change v2 that pares back a bunch of the deprecated stuff.) Unfortunately since we pull the reference documentation directly from the ripple-lib repository, these changes are a little more challenging to implement.
Ripple Data API v2 → This is the third "Ripple API" on this page, although at least this one has a key word "Data" in there to tell you something useful about it. Unfortunately, it's deprecated!
xrp-ledger.toml file → "One of these things is not like the others." Where the other ones are mostly specifications for programming interfaces, this is a document format.
Not present on this page, but probably should be: xrpl4j, xrpl-py, and potentially other/future libraries.
We should reorganize the page, probably with a more carefully curated and visually stimulating layout that elevates the content that's most useful and better distinguishes between similarly-named stuff.
After discussion with some experts, here are some more specific action items:
[ ] Remove Data API. Leave a placeholder with the deprecation notice and a link to the GitHub README where the API docs remain.
[ ] Remove XRP-API docs. Point to generated docs in the XRP-API repo's Github Pages or something
[ ] (Details TBD) Split off certain aspects of the "rippled API" reference into an "XRP Ledger Protocol" reference. Transaction types, ledger data formats, etc.
[ ] Rename "rippled APIs" to "XRP Ledger HTTP API"
[ ] Title / categorize client libraries by programming language. e.g. instead of "RippleAPI" have it be "JavaScript / TypeScript Client Library" or something like that
The References landing page is a very confusing landing page that could provide a lot better direction and context around what reference content exists on xrpl.org.
There are four top-level items, all with confusing names, and they aren't particularly representative of what people might want to do with the XRP Ledger:
Not present on this page, but probably should be: xrpl4j, xrpl-py, and potentially other/future libraries.
We should reorganize the page, probably with a more carefully curated and visually stimulating layout that elevates the content that's most useful and better distinguishes between similarly-named stuff.