Best Practices for Technical Writing: API Documentation

Introduction:

API documentation is an essential part of software development. It provides technical details for integrating with an application programming interface (API) and helps developers automate tasks, retrieve data, and perform actions within a platform.

However, writing effective API documentation can be challenging, especially when it comes to presenting complex technical information in a clear and concise way.

In this article, we will compare how a technical documentation can be written in Markdown and using DITA XML.

Example 1: API Documentation in Markdown

Markdown is a lightweight markup language that is easy to read and write. It is widely used for writing documentation and README files for software projects.
Here’s an example of technical writing for API documentation in Markdown:

Introduction

This API documentation provides technical details for integrating with our platform. Our API allows developers to automate tasks, retrieve data, and perform actions within our platform.

Authentication

Authentication is required for all API requests. We use OAuth 2.0 to authenticate requests. To authenticate, developers must obtain an access token by following these steps:

Register your application with our platform and obtain your client ID and client secret.
Request an authorization code by sending a GET request to our authorization endpoint.
Exchange the authorization code for an access token by sending a POST request to our token endpoint.

API Endpoints

Our API provides the following endpoints:

Endpoint 1: /users

Description: Returns a list of all users in the system.

HTTP Method: GET

Parameters:

None

Response:

Status Code: 200 OK
Body: List of user objects

Endpoint 2: /users/{id}

Description: Returns details for a specific user.

HTTP Method: GET

Parameters:

id (required): The ID of the user to retrieve.

Response:

Status Code: 200 OK
Body: User object

Endpoint 3: /orders

Description: Returns a list of all orders in the system.

HTTP Method: GET

Parameters:

start_date (optional): The start date for the range of orders to retrieve.
end_date (optional): The end date for the range of orders to retrieve.

Response:

Status Code: 200 OK
Body: List of order objects

Error Codes

Our API may return the following error codes:

400 Bad Request: The request was invalid or malformed.
401 Unauthorized: The request was not authenticated or the access token was invalid.
404 Not Found: The requested resource could not be found.
500 Internal Server Error: An unexpected error occurred on our server.

Conclusion

Thank you for reviewing our API documentation. Please contact us if you have any questions or feedback.

Example 2: API Documentation in DITA XML

DITA (Darwin Information Typing Architecture) is an XML-based architecture for creating technical documentation. It is a standard for writing technical documentation and is widely used in the industry. Here is an example of the same API documentation written using DITA XML:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="api_documentation">
  <title>API Documentation</title>
  <body>
    <p>This API documentation provides technical details for integrating with our platform. Our API allows developers to automate tasks, retrieve data, and perform actions within our platform.</p>
    <section id="authentication">
      <title>Authentication</title>
      <p>Authentication is required for all API requests. We use OAuth 2.0 to authenticate requests. To authenticate, developers must obtain an access token by following these steps:</p>
      <ol>
        <li>Register your application with our platform and obtain your client ID and client secret.</li>
        <li>Request an authorization code by sending a GET request to our authorization endpoint.</li>
        <li>Exchange the authorization code for an access token by sending a POST request to our token endpoint.</li>
      </ol>
    </section>
    <section id="api_endpoints">
      <title>API Endpoints</title>
      <p>Our API provides the following endpoints:</p>
      <table>
        <tgroup cols="3">
          <colspec colname="endpoint"/>
          <colspec colname="method"/>
          <colspec colname="parameters"/>
          <thead>
            <row>
              <entry>Endpoint</entry>
              <entry>HTTP Method</entry>
              <entry>Parameters</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry>/users</entry>
              <entry>GET</entry>
              <entry>None</entry>
            </row>
            <row>
              <entry>/users/{id}</entry>
              <entry>GET</entry>
              <entry>id (required): The ID of the user to retrieve.</entry>
            </row>
            <row>
              <entry>/orders</entry>
              <entry>GET</entry>
              <entry>start_date (optional): The start date for the range of orders to retrieve.<br/>
                     end_date (optional): The end date for the range of orders to retrieve.</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </section>
    <section id="error_codes">
      <title>Error Codes</title>
      <p>Our API may return the following error codes:</p>
      <table>
        <tgroup cols="2">
          <colspec colname="code"/>
          <colspec colname="description"/>
          <thead>
            <row>
              <entry>Code</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry>400</entry>
              <entry>The request was invalid or malformed.</entry>
            </row>
            <row>
              <entry>401</entry>
              <entry>The request was not authenticated or the access token was invalid.</entry>
            </row>
            <row>
              <entry>404</entry>
              <entry>The requested resource could not be found.</entry>
            </row>
            <row>
              <entry>500</entry>
              <entry>An unexpected error occurred on our server.</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </section>
    <p>Thank you for reviewing our API documentation. Please contact us if you have any questions or feedback.</p>

Conclusion:

API documentation is an important part of software development, and it is essential to present technical information in a clear and concise way. Writing effective API documentation requires attention to detail and an understanding of the target audience.

Whether you use Markdown or DITA XML, following best practices for technical writing can help ensure that your API documentation is well-written, informative, and easy to understand.

By incorporating these best practices into your writing, you can create API documentation that is valuable to developers and helps them use your API effectively.

Found this article helpful? Post in your feedback or queries in the comments below!