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.

Improve this question
14
  • Hmm, there's not a ton of suggested edit reviewers there either, are there?
    – Nathan Tuggy
    Commented Jan 23, 2017 at 19:14
  • 2
    Clearly the API documentation should be moved to SO Docs.
    – Jeffrey Bosboom
    Commented Jan 24, 2017 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 StaffMod
    Commented Jan 30, 2017 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?
    – bb216b3acfd8f72cbc8f899d4d6963
    Commented Jan 30, 2017 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 StaffMod
    Commented Jan 30, 2017 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
    Commented Jan 31, 2017 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
    Commented Mar 29, 2018 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 StaffMod
    Commented Mar 29, 2018 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 StaffMod
    Commented Mar 29, 2018 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
    Commented Mar 29, 2018 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 Wizard
    Commented Mar 29, 2018 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 StaffMod
    Commented Mar 29, 2018 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
    Commented Mar 29, 2018 at 15:49
  • 2
    @JonEricson please don't give users false hope and pretend that these reports will be looked at...
    – Stijn
    Commented Jun 4, 2018 at 12:37

0

Reset to default

You must log in to answer this question.

Browse other questions tagged .