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'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include the following technical communication topics: Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, and certificate programs. I'm interested in information design, API documentation, visual communication, information architecture and findability, and more. If you're a professional or aspiring technical writer, 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.