Mastodon: Please move the API documentation back to the main repository

[ghost]

The API documentation hasn't been updated in months despite several changes, like https://github.com/tootsuite/mastodon/pull/3017 and https://github.com/tootsuite/mastodon/commit/2925372ff44347fa7066c380a5d51dd35f80682f .
Requests for improvements or at least maintenance (https://github.com/tootsuite/documentation/issues/267 , https://github.com/tootsuite/documentation/issues/336) remain unanswered.

If the API documentation (not all the documentation, just the API parts) is moved back to the main repository, the developers and contributors can be reminded that the documentation exists, and to include appropriate documentation updates in their pull requests.

---

• [X] I searched or browsed the repo’s other issues to ensure this is not a duplicate.

[nightpool]

Keeping documentation up to date is a perennial issue, and I don't think changing which repo the docs are in is going to have more then a short-term effect.

I think the best solution is to have documentation auto-generated in some way from the rails source files, so that it gets much harder to update the source without touching the documentation. I don't know what people's experience with this is, but I've used json schema files with test/CI errors for endpoint responses that don't match the schema, so that's one option i'm aware of.

that said, I don't think I understand why the documentation was moved to another repo to begin with, given that it seems to make it very hard to maintain any of the documentation, not just the API docs. Can someone involved in that discussion lay out the reasoning for it?

[wxcafe]

I believe it was moved to a different repo to minimize the volume of commits/PRs that were only about modifying the doc.

To be fair, the problem is mostly that the doc doesn't get updated. Where it is doesn't really matter. Having an automated process populate the docs would be :100: