Podcast: Unifying the API doc publishing toolchain, with Mark Baker
Listen here:
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 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.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.