14

The API documentation has more than a few typos, errors, and unclear bits. Many of these have been noted in comments over the years and there are 44 bug complaints on Stack Apps. (That's a LOT of activity for Stack Apps).

Other sites also occasionally report API documentation problems. For example, there are at least 4 here on Meta SE.

Currently, documentation apparently needs an SE developer to edit, and the last doc bug to be resolved was 3 years ago!

So, please allow users to edit the documentation. We can fix all those niggling typos. Maybe treat it the same as a tag wiki as far as suggested edits are concerned.



But maybe lower the unrestricted editing privilege, since there is only one 20K user and he hasn't done any moderation in ages.

  • Hmm, there's not a ton of suggested edit reviewers there either, are there? – Nathan Tuggy Jan 23 '17 at 19:14
  • 2
    Clearly the API documentation should be moved to SO Docs. – Jeffrey Bosboom Jan 24 '17 at 4:55
  • 5
    We are planning on most of the API documentation to Documentation sometime this spring. We've had several companies express interest in embedding an API console on Docs and the obvious way to build that up is with our own API. For now I'm marking this as planned and more details will follow as we know more. – Jon Ericson Jan 30 '17 at 21:55
  • @JonEricson Does this mean a sort of command line interface for testing Node.js or other languages? If so, will they be able to be copied from a code block into the CLI? – haykam Jan 30 '17 at 23:10
  • @haykam: That's not in the plans at the moment. To keep things simple, we'll probably just copy the existing "Try It" section. (I see there's some potential confusion by my phrasing. That's all I meant by "console".) – Jon Ericson Jan 30 '17 at 23:23
  • @JonEricson That's great, the only thing preventing a move to Documentation currently is the lack of a "Try It" section. I'm working on an API client in my spare time currently, and writing docs in the process. Can I put those docs on Documentation already, or do you prefer waiting until you have more details? – Stijn Jan 31 '17 at 11:48
  • 1
    Hi @JonEricson, just wanted to pass along some frustration felt by myself and a number of other users new to the API, entirely related to obvious errors in the documentation. Beyond the wasted hours & headaches, this could cause "unintentional abuse" of the API by apps planned around faulty information. Do you happen to know a timeline for the changes you mentioned? In the meantime, if you were to ¼ the req'd rep to edit the docs, still only 4 [recently active] users would have the privilege but would make a big difference. – ashleedawg Mar 29 '18 at 2:41
  • @ashleedawg: Unfortunately, we had to shut down Documentation last year. So we don't plan on allowing users to edit the API documentation anymore. However, we do welcome bug reports and feature requests here on Meta Stack Exchange. Use the api tag and we'll get it to the developers. Sorry to disappoint. :-( – Jon Ericson Mar 29 '18 at 5:24
  • 1
    One more hopeful item to relay is that Enterprise and Teams are gearing up to offer the API to customers. As much as possible we are working to keep the code and documentation synced across all three products. That means there's some hope API bugs and feature requests will be addressed more quickly than in the past. – Jon Ericson Mar 29 '18 at 5:29
  • @JonEricson So what's the preferred way to have typos fixed in the API documentation? Report a bug on Meta for each? – Sonic the Anonymous Hedgehog Mar 29 '18 at 5:44
  • 1
    @Jon can you please explain the decline in an answer? Comments are temporary and can vanish without notice. Also, how is Documentation relevant? Maybe you misunderstand the request here? It's about the API used by programmers, not about the dead Documentation project. (I removed the misleading tag.) – Shadow Mar 29 '18 at 6:58
  • @SonicWizard: Probably depends on the typos. If you have a pile of its <=> it's, spelling and grammar changes, maybe put it in a single post so you don't flood meta with trivia. If it's a more nuanced and individual problem, like a mismatch between the documentation and the way the API behaves, that might work better in a separate question. – Jon Ericson Mar 29 '18 at 15:44
  • 1
    @ShadowWizard As Jon Ericson mentioned earlier, there was a plan to move API docs to Documentation, which would make it editable. – Sonic the Anonymous Hedgehog Mar 29 '18 at 15:49
  • 2
    @JonEricson please don't give users false hope and pretend that these reports will be looked at... – Stijn Jun 4 '18 at 12:37

You must log in to answer this question.

Browse other questions tagged .