Why API Documentation Fails: Platform vs Web APIs and the Hidden Pitfalls

1. Everything Starts with the API Itself

1. What Is a Platform API?

Platform API, i.e., class‑based API, includes Java, C, C++, C#, VB and similar languages. It is essentially a library that can be integrated into your code, allowing you to call its classes to extend program functionality.

2. What Is a Web API?

Web API (Web service API) communicates via the HTTP protocol. You send a request to a specific URL and receive a response in a browser. REST API and SOAP API are types of Web service APIs; REST is language‑agnostic and works with endpoint URLs.

3. Have You Considered the Pros and Cons of Platform APIs?

Advantages:

Performance: Platform APIs are libraries called by the program, becoming part of the compiled application.

Security: Interaction stays within the program, improving security compared with external REST calls.

Disadvantages:

Language coverage: Platform APIs are language‑specific; a Java API can only be used in Java, requiring separate APIs for each language.

Upgrades: When the API provider changes the API, developers must recompile their programs.

4. What Is the Current State of Platform API Documentation Automation?

Many API documents are generated automatically from source‑code comments using tools such as Javadoc.

Developers or documentation staff add descriptive text directly as comments in the source code.

Tools like Javadoc then convert those comments into formatted API documentation.

5. What Is the Automation Status of Web API Documentation?

Some teams use custom scripts or tools to output API docs, but these are often not integrated into the build process. Industry surveys show that 58 % of REST APIs are still documented manually, indicating low automation levels.

6. Who Writes Javadoc? How?

Typically engineers write the initial draft directly in the source code. Technical writers then edit and improve the drafts, usually working in small teams handling multiple API documents.

7. Are There Advantages to Writing Inside the Source?

Advantage 1: Avoid documentation drift—keeping docs synchronized with code.

Advantage 2: Engineers have deeper understanding of the code they write.

Advantage 3: IDE tooltips can assist when comments are written inline.

2. The Three Sins of Writing Inside Source Code

Despite the benefits, three major pitfalls undermine the quality of auto‑generated API documentation.

Professional documentation writers often dislike automatically generated docs (e.g., Javadoc) because they lack manageability, reusability, maintainability, and openness, and they give developers excuses to write less documentation.

Gives illusion of real doc

Doesn't integrate

Curse of knowledge

These sins lead to fragmented, hard‑to‑navigate documentation that fails to serve developers effectively.