1. I'd Rather Be Writing
2. Docs
3. Chapter 13: Native library APIs

Create non-ref docs with native library APIs

Download PDF

Although much attention tends to be given to the reference documentation with APIs, the bulk of documentation that technical writers work on (as opposed to developers) is conceptual documentation. Developers rarely write more conceptual or tutorial-based documentation.

Engineers will throw a quick description of a class in a file and generate a Javadoc, and they’ll give that Javadoc to the user as if it represents a complete set of documentation — but reference docs don’t tell even half the story.

• Reference docs can be an illusion for real doc
• Reference docs are feature-based, not task-based

Reference docs can be an illusion for real doc

Jacob Kaplan Moss says that reference docs can be an illusion:

… auto-generated documentation is worse than useless: it lets maintainers fool themselves into thinking they have documentation, thus putting off actually writing good reference by hand. If you don’t have documentation just admit to it. Maybe a volunteer will offer to write some! But don’t lie and give me that auto-documentation crap. – Jacob Kaplan Moss

Other people seem to have similar opinions. In general, document generators don’t tell you a whole lot more than you would discover by browsing the source code itself. Some people even refer to auto-generated docs as a glorified source-code browser.

Reference docs are feature-based, not task-based

One of the main problems with reference documentation is that it is feature-based rather than task-based. It’s the equivalent of going tab-by-tab through an interface and describing what’s on each tab, what’s in each menu, and so on. We know that’s an ineffective way to approach documentation since users often organize their mental model by the tasks they want to perform.

When you write API documentation, consider the tasks that users will want to do, and then organize your information that way. Reference the endpoints as you explain how to accomplish the tasks. Users will refer to the reference docs as they look for the right parameters, data types, and other class details. But the reference docs won’t guide them through tasks alone.

About Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.