Podcast: Unifying the API doc publishing toolchain, with Mark Baker
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 a technical writer based in the Seattle area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out simplifying complexity and API documentation for some deep dives into these topics. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates. You can also learn more about me or contact me.