---
title: "Podcast: Unifying the API doc publishing toolchain, with Mark Baker"
date: 2015-01-08
description: "$( document ).ready(function() { // Handler for .ready() called. $('#toc').toc({ minimumHeaders: 3, listType: 'ul', showSpeed: 0, headers: '#content h2, #content h3, #content h4, #content h5, #content h6' }); /*..."
canonical_url: https://idratherbewriting.com/2015/01/08/podcast-unifying-the-api-doc-publishing-toolchain-with-mark-baker/index.html
---

> For AI agents: a documentation index is available at https://idratherbewriting.com/llms.txt. Markdown versions of all pages are available by appending .md to any page URL.

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

**Listen here:**

[Audio](https://www.podtrac.com/pts/redirect.mp3?https://s3.us-west-1.wasabisys.com/idbwmedia.com/podcasts/markbakerunifyingapidocpublishing.mp3)

[![](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/apple_podcasts.png)](https://itunes.apple.com/us/podcast/id-rather-be-writing-podcast/id277365275) [![](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/watchonyoutubeblack.png)](https://www.youtube.com/@idratherbewriting) [![](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/spotify.png)](https://open.spotify.com/show/4HeOZfPGMMfViOhVS40QBD)

In this podcast, I talk with Mark Baker from [Every Page Is Page One](http://everypageispageone.com/) 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](https://parse.com/docs/android_guide)) 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 Baker](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/mark-baker-125x125.png)](http://everypageispageone.com/about/)[Mark Baker](http://everypageispageone.com/about/) 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](http://xmlpress.net/publications/eppo/) and even developed his own XML-based architecture called [SPFE](https://mbakeranalecta.github.io/spfe-open-toolkit/). He has a blog at [EveryPageIsPageOne.com](http://everypageispageone.com/), where he provides thought leadership on best practices for technical communication, particularly in optimizing documentation for the web.