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.
I'd Rather Be Writing Newsletter
Get new posts delivered straight to your inbox.
About Tom Johnson
I'm a technical writer based in the California San Francisco Bay area. In this blog, I write about topics related to technical communication — Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, academics, and more. I'm interested in simplifying complexity, API documentation, visual communication, information architecture and findability, and more. If you're a technical writer of any kind (progressional, transitioning, student), be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.