API Documentation Writing is not Technical Writing
Many see API documentation writing as technical writing. It’s not. Here’s why.
Technical writing is often seen as being all the same. Any technical writer can be hired to write any technical documents. Think of software and software manuals. Writers look at their screens and document what they see. It’s true, there is that aspect, though that’s not the only aspect. This perception is at the core of the problem. There are different types of technical writing: Software, medical, and API technical writing.
Difference #1: It’s a Specialty
Medical writers will tell you their profession is about medical writing. It’s medical. API documentation writing is that specialized, too. It’s about programming. The required skills include everything from being able to read and write code, examples, and even complete entire applications showcasing calls. They often have computer-related or programming-related degrees, or may have been titled programmers in the past. This means they’ll know the parlance, jargon, and programming terms so as to be able to talk with programmers. All the while, explaining this in clear and precise grammar. For these reasons, this is on par with the medical writer. In contrast, some companies hire junior technical writers for this role, and then are surprised when the documentation doesn’t work out. I never tire of vilifying CEOs who hire top-notch programming talent but skimp on API documentation writers. So, the extent of the specialized skills makes this apart from general technical writing
Difference #2: Managing API Documentation Projects
Here, I get to be critical of documentation managers. Many don’t have direct experience with API documentation. These managers will manage as they know how to: For technical writing. The fix for that is to listen to the API documentation writers; after all, they were hired for their expertise and experience.
For example, one manager told me all I had to do is enter a command into Postman, an API testing application, and document what I see. That sounds an awful lot like their perception of technical writing mentioned earlier: Look at a screen and document what you see. Again, superficially there is that aspect. But his conclusion was that API documentation is actually easier than technical writing.
What he didn’t understand, even when explained to him, is there's more to it. It’s almost never just one call; it’s series of tests. It’s possible to spend an entire day, if not more, on one call. Parameters have to be explored, there are combinations of parameters, the scenarios have to be set up, and finally, everything written up as a cohesive whole.
The writer probably has to find that information themselves. That happens only by experimenting with the call, even with good specs. Clearly, we’re not just making a call and documenting what we see. We’re making a call a dozen times with different values. Can the parameter be null, 0, 1, more, more than the items in a list? And then there’s the issue that API documentation writers anticipate questions. If there is an obvious or logical case that we think is going to get asked, we need to answer it ahead of time. For example, what if an expected file isn’t present when the call is made? Is that an error? The parameter is ignored? Is there a default value? If so, what is the default information? And no, looking at the code doesn’t always answer that.
A documentation manager who views API documentation as a technical writing project is going to severely underestimate the project schedule. It’s not just a matter of dictating schedules, such as ten calls in four days. The calls may not be uniformly deep, or one call requires a significant amount of time more than the others. If they don’t treat it as a specialty, why would they expect to get specialty results? There are no good results otherwise:
· Documentation managers get the schedule they want but realize it’s not the product they want.
· The writers rush through and couldn’t provide the level of detail they want.
· The clients don’t have the documentation they want.
Difference #3: There is no end in sight
This is the tough point for managers new to API documentation: There is no end. Take the representative technical writing task where they “ look at their screens and document what they see.” The truth is there’s only so much that can be written using that approach. From a sign-in screen, to a complex concept, perhaps unique to the product or industry.
This is not necessarily the case for API documentation. Often, it is possible to add a copious amount of details. Keep in mind, the API documentation is to be the single source of truth for the programmers. That means each parameter has to be completely explained. A deep API product has too much detail to be added in at a single time. So, creating an API documentation suite is actually a series of passes, with each pass adding more detail.
That means management and the API documentation writers have a negotiation between deadlines and completeness. For example, how much can be finished in four weeks? 10%, 30%, 100%? On the other hand, how long will take to reach 30%
Conclusion
The documentation suite, for whatever level of detail they agreed on, has to be complete for that level. Getting there is a negotiation between the writers and management. Since management may not have the experience with API documentation suites, they are wise to listen to their API documentation writers.