4 Replies - 157 Views - Last Post: 14 May 2019 - 05:16 PM

#1 Bzonana   User is offline

  • New D.I.C Head

Reputation: 0
  • View blog
  • Posts: 1
  • Joined: 14-May 19

What is good API documentation?

Posted 14 May 2019 - 03:47 PM

Full disclosure, I am a product manager and my technical abilities are low (which I wish I could change overnight to be better for my team, but regardless here I am asking what I know to be a stupid question.)

I on day 4 of a new job, and I've been tasked with creating API documentation for our customers due tomorrow night. So I'm a noob, barely have a grasp on REST vs SOAP and I genuinely want to create great documentation, but I don't have the first clue where to start.

Can you guys offer any guidance on the right questions to ask my dev team? Or examples of good documentation? Or things to look for? Or basics to know?

For context, the documentation will end up in a PDF format delivered to customers and I've been told I need to include an intro, body, and potential error messages. Is there anything else that I should think about including?

Any and all help, would be greatly appreciated.
-BZ

Is This A Good Question/Topic? 0
  • +

Replies To: What is good API documentation?

#2 Sheepings   User is offline

  • Senior Programmer
  • member icon

Reputation: 223
  • View blog
  • Posts: 1,260
  • Joined: 05-December 13

Re: What is good API documentation?

Posted 14 May 2019 - 04:19 PM

Welcome to the website. :)

Frankly I don't think you should be in the position you are in if you need to ask that question. Or are you just getting the jitters because its a new job or something? And I'd be most surprised to discover someone can advise you without more information. What is the project you were tasked with about? Certainly you may get better reception if you can be a bit more forthcoming to provide more clarity re the project you're tasked with.

I also don't think this is a suitable forum for such discussion. Perhaps a mod will move it to an appropriate forum if its not ASP related.
Was This Post Helpful? 0
  • +
  • -

#3 modi123_1   User is online

  • Suitor #2
  • member icon



Reputation: 14992
  • View blog
  • Posts: 59,853
  • Joined: 12-June 08

Re: What is good API documentation?

Posted 14 May 2019 - 04:50 PM

"api documentation format" brings up a whole mess of free help and online classes.

For the most part you need to describe enough of what is going on that some third party can pick up the gist and implementation for the API with minimal input.
Was This Post Helpful? 0
  • +
  • -

#4 jon.kiparsky   User is offline

  • Beginner
  • member icon


Reputation: 11500
  • View blog
  • Posts: 19,573
  • Joined: 19-March 11

Re: What is good API documentation?

Posted 14 May 2019 - 05:01 PM

Document an API, overnight? Oy gewalt.

Given that timeframe, spend your attention on the thing you know is distinct about your API, which is the endpoints. What are they, what do they mean, what do I need to know about them to use them effectively?

If you want to write an "intro" it should basically give your users the background to understand what the endpoints are about, so basically key concepts of your product (if there are any interesting ones)
Was This Post Helpful? 0
  • +
  • -

#5 Sheepings   User is offline

  • Senior Programmer
  • member icon

Reputation: 223
  • View blog
  • Posts: 1,260
  • Joined: 05-December 13

Re: What is good API documentation?

Posted 14 May 2019 - 05:16 PM

While every API is different due to the variety of types; class based APIs, os functions/routines, web services APIs to name a few. In theory, if you know the functionality of said API, you should know how to describe its use. There are private API, Open API, and internal API, It's actually a kinda vague question. Writing full docs in one night, while not impossible, certainly depends how big it is.
Was This Post Helpful? 0
  • +
  • -

Page 1 of 1