Hi, I work in the FrameMaker and InDesign worlds providing automation for technical writers. I am looking to expand into the world of API documentation and would like to know a general overview of the process of creating API docs and what the bottlenecks and challenges that writers encounter in their work. I am interested in learning about tools and how API docs are integrated into other publications, etc. I would love to see samples of API docs and how they are typically structured. If you are willing to meet with me via web meeting, I would appreciate it. Thank you. -Rick
Check the API Writers group on LinkedIn. I just replied to someone looking for similar information. The first challenge is that you need to know at least one programming language. Almost all current API documentation is built from comments in source code. Depending upon the language/framework/operating system of your development environment, there is a process of extracting the comments, applying some transformations and formatting tags (ala CSS), and producing output in various formats, typically HTML and PDF.
With apologies for the late reply:
What you need really depends on the APIs in question, though. What @SnoopDougieDoug says was true once upon a time, but is rarely true (and I’ve never seen it effectively implemented) in the world of CRUD over HTTP, otherwise commonly known as REST (REST encompasses far more, and continues to develop, but most “RESTful” APIs are still at the CRUD over HTTP level). And these are the APIs that have been getting all the attention in recent years.
TL;DR: there’s no clean simple solution.
Read Bob Watson’s blog, and see whether his webinar is recorded (or maybe you caught it live – see his forum post).
Also, take a look at Tom Johnson’s material on his blog, http://idratherbewriting.com/, and hang out at your local API meetups. If you’re not familiar, start with APIs, not with docs. There’s a tremendous amount of interest in docs in the API community. Also, be prepared to move outside the world/s of FrameMaker and InDesign.
Another late reply – I’m sorry I didn’t see this sooner!
Peter Gruenbaum has three API doc courses available on Udemy: https://www.udemy.com/user/petergruenbaum/
They’re $10 each right now.
I also went through Tom Johnson’s API course (http://idratherbewriting.com/docapis_course_overview/), which @bradamante mentioned as a resource. It’s a lot of free information – I thought it was great.
Hi - I’m also looking to learn more about API docs. Unfortunately, we’re not using REST, so all the wonderful REST tools out there aren’t helpful for us.
Can anyone point me to anything for non-REST APIs - other than DocumentX?
@batamig can you tell us a bit more about your APIs? SOAP? Classic interfaces? Language? doxygen supports scraping code comments from a wide range of languages, but its output is only as useful as the effort that folks put into said comments. And you need more than the reference docs, but depending on how you want to publish your content, you can work with other tools for different kinds of content.
Thanks! Our group currently mainly uses DocumentX to generate .NET or VBScript SDK and API references. We also use JavaDoc for our JavaDoc SDK ref and JSDoc for our JS SDK ref. We already work with dev on writing the actual comments and examples so that wouldn’t change regardless of the tool. The main issue now is finding one tool that can cover them all - then we can become more expert in that tool.