Search results

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

by Tom Johnson on Jan 8, 2015
categories: api-doc podcasts * TOC {:toc}

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?

Sponsored content

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.

Buy me a coffeeBuy me a coffee