Presented by Tom Johnson, and reviewed by Mysti Berry
Tom Johnson, author of the blog I’d Rather Be Writing (idratherbewriting.com) shared current practices and trends in API publishing. Access the slides and recorded meeting from his website(http://idratherbewriting.com/2014/10/16/api-doc-presentation-slides-and-recording/).
Hint: Be sure to look for his list of API sites to study, and the ten trends and anti-trends in API documentation.
Important features for any API documentation include:
- A getting started section, including how to import a native API or simple queries for a web-based API. For web-based API, you may need to just pick a language, like cURL and JSON. Most companies don’t have enough in-house resources to produce every example in three or four languages, so find out what most of your customers use.
- Many examples, especially robust examples, using syntax highlighting and adding narrative explanation to clarify the example. Some documentation displays a “copy this example” tool as well.
Tom explained the two different types of API:
- Native: you download an API and add it to your development project.
- Web-based: SOAP, REST, or similar interfaces are available to anyone with the correct credentials. You can usually create projects in whichever language you choose, as long as you can send JSON or XML to the API and receive the results.
Techniques that work for native API may not work for REST or SOAP. For example, auto-generated documentation is difficult for REST, which relies on URLs and standard HTTP methods.
Key trends include:
- API documentation that looks beautiful.
- Navigation that favors scrolling over link clicking.
- A growing a desire to combine automated content with content that writers create.
There are features that no one wants, mostly as a result of most developer’s preference for scrolling rather than link clicking:
- Collapsible sections and short topics
- Tri-pane HTML
How can a writer create beautiful, scrolling content for their API developers? Tom presented over a dozen tools by category. Hosted solutions, wiki-type solutions, DITA, site generators and content auto-generators like Doxygen or Javadoc. Each has its benefits and drawbacks. Check out his slides for a fantastic list to help you start exploring the options.
Tom shared his experience using WordPress, and several other wiki-based approaches. Some people think of WordPress as a platform for non-technical blogs, but Tom’s work showed that it can integrate with DITA.
During the Q&A it became clear that tools and processes differ widely depending on whether you have a small set of interfaces or a large set, and whether you are the “lone writer” for your API efforts or have a team of other writers and developers to support you. Finally, it’s clear that a lot of people are trying to invent the perfect solution. Tom made it clear that we have a few years of experimentation and new solutions to work through before any one solution becomes the default.
Bio: Mysti Berry writes enterprise software documentation, including SOAP and REST API documentation. She currently lives in San Francisco, and works for Salesforce on the developer documentation team.