Podcast: Unifying the API doc publishing toolchain, with Mark Baker
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 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.
