Stay current with the latest in tech comm
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,000+ subscribers

Stitcher radio

Search results

Announcement:
I'm giving an API documentation workshop in Mountain View, California on August 30, 2019. If you're interested, you can register on EventBrite.

Podcast: Unifying the API doc publishing toolchain, with Mark Baker

by Tom Johnson on Jan 8, 2015 • 0 Comments
categories: api-docpodcasts

Length: 62 min.

Download MP3 (right-click and select Save As)

In this podcast, I talk with Mark Baker from Every Page Is Page One about unifying the API doc publishing toolchain. Here are some questions I ask Mark during the podcast:

  • What kinds of API docs pose challenges with the tool chain?
  • Do API reference docs need to be separate from other docs?
  • How do you integrate API reference with non-API reference info?
  • How do you extract source code comments from Java or C++ and push them into another publishing chain?
  • How can the structure of source-code comments be parsed and transformed into another format?
  • Is there value in publishing Java API doc in a syntax familiar to Java developers (Javadoc)? same with C++ (Doxygen)?
  • What are the best publishing strategies for REST API documentation?
  • Is XML (as opposed to Markdown or some other format) the right markup for API doc?
  • What are some limitations with DITA with respect to publishing API doc?
  • What advantages does SPFE have for API documentation?
  • What is a top-down architecture versus a bottom-up architecture?
  • What do you mean by tightly coupled versus loosely coupled?
  • What are your thoughts on single-page docs (such as parse) that load more content on scroll versus docs that separate out into multiple pages?
  • Are there any API doc sites that you think serve as particularly good examples of how to do API documentation right?
  • Can StackOverflow be considered API documentation?

About Mark Baker

Mark BakerMark Baker is guru when it comes to publishing structured documentation on the web. He articulated his approach in a book titled Every Page Is Page One and even developed his own XML-based architecture called SPFE. He has a blog at EveryPageIsPageOne.com, where he provides thought leadership on best practices for technical communication, particularly in optimizing documentation for the web.

follow us in feedly