OK, I think I understand better, thank you.
What follows are my own opinions – I haven’t run these by people more knowledgeable than myself, so I may get corrected on a few things that I’m getting wrong here.
Our story documentation is also evolving. We’ve made significant strides, but there’s a long way to go. Allow me to try to recap a bit.
First, as a kind of higher level mental model, I’d describe things like this:
- Our main entrypoint for documentation is here, as you pointed out: Documentation - Discourse Meta
- For developer documentation, it’s here, or perhaps better yet, here: Introduction to Discourse Development
- API docs are a subset of developer docs, and are located here: https://docs.discourse.org/
- For developer documentation, it’s here, or perhaps better yet, here: Introduction to Discourse Development
I would call the API docs docs rather than specs, but I agree they are still a subset of our developer docs. The URL for those docs is odd… it’d make more sense for our full documentation to live there or for that to be a redirect to https://meta.discourse.org/c/documentation/10, and for there to be a clear signpost from Introduction to Discourse Development to the API docs.
Our developer docs are themselves undergoing improvements. The commit history here probably tells the best story about where the effort has gone so far: Commits · discourse/discourse-developer-docs · GitHub
The API docs could be described as incomplete, but we have work to do to get our story straight here. In the past, we used to point to “reverse engineer the API”, but I agree that’s not a good story. It’s fine for hacking at your own risk, but there may be cases where endpoints not listed there are probably better not to depend on.
The server side API is intended primarily to be consumed by our frontend application. On the frontend, we provide a JavaScript API that’d be a better interface to consume as it can hide changes made to the backend: Using the JS API
So what stability guarantees can we be making about our backend API?
I think that’s a responsibility those API docs should be addressing. Ideally, what’s documented there is a subset of all the endpoints we support, but an intentional subset that we aim to support for others building integrations, whereas things not listed there are intentionally not documented as being things only intended for our frontend, which may change without notice.
Ideally (in my mind), we’d have documentation be built into the source code in a way that the docs themselves are under test, extensible with plugins, served by the app itself so they are in sync with the instance that’s being documented – that way you could view the API docs for a given site and see documentation for the version its running, with whatever plugins are actually installed and enabled.
I know others internally have had plenty of discussions about other ideas for improving our server side API story.
We’ve not been able to prioritize much in this space yet, as our primary focus when it comes to developer experience for the past couple years has been on modernizing our frontend.
I’m not sure when that’s likely to change, but we’ll keep an eye out for smaller things we can be doing along the way to keep chipping away at the server side API story. If there are specific questions that surface, perhaps we can use those as the impetus to make more targeted improvements in the meantime.