Tools FAQ
- Q: Is it possible to author API documentation using DITA/XML or an XML editor (like Oxygen)? I saw your recommended list of tools in the Publishing API docs section, but it would be great if we could leverage existing tools.
-
Sure, you can use OxygenXML or similar tools and write your dev docs in DITA. However, for the reference content, if you’re working with REST APIs, I recommend documenting the endpoints using the OpenAPI spec. If documenting class-based libraries, then use in-code annotations for that language.
- In the dev doc survey I conducted about dev doc trends, about 11% of people writing docs for devs use XML-based solutions, so you wouldn’t be alone. However, if you’re intending to solicit contributions from engineers, and you have a lively and engaged developer community who will actually be contributing to docs, then I do not recommend XML solutions. Use Markdown instead.
- Q: We use Madcap Flare but document our APIs in Swagger. We’re considering dropping Flare and using Readme.com instead, which can import Swagger, but should we be looking at other tools? We also don’t document just APIs, but have protocols we document outside of the APIs too.
-
MadCap Flare is a much more robust tool for handling documentation than Readme.com. For example, last time I checked, Readme.com doesn’t let you store content for re-use. There was a recent discussion in the #documenting-apis channel in WTD Slack about Readme.com. More people seem to be abandoning Readme.com to pursue a more flexible platform. I asked for more details. One person said, “Outages, organizing content. I didn’t use it much myself. … After your reference specs and examples are in readme.com, you’re limited in what you can get out. If nothing else, that’s a mark against them.” In short, sure Readme.com can import and display reference API content well (if you like the design), but if you’re stuck using a simple editor for everything else and can’t leverage more powerful tools for other doc management, life might get more challenging. That said, many top companies use Readme.com and the output looks professional and industry-aligned.
- Personally, I recommend going with a static site generator (SSG) for dev docs instead of a third-party online hosted platform. SSGs are the trend for a reason — they’re way more fun, flexible, and engineering-oriented. If you aren’t into developing your own site, though, you can also look at some alternatives in this same hosted doc category – Developerhub.io, Readthedocs.com. If you’re doing heavy localization and generating lots of PDF, probably stick with your existing tool. Generate out your reference using Redoc, Swagger, or other specialized generators.
