Technical Documentation: The Lost Art Form

Wes Wise, Ytel |  

With the Ytel API and its correlating documentation, we offer a rounded service for consumers to take full advantage of, from getting initially set up all the way to using advanced functionality. This all comes down to one guy, Wes Wise, who was brave enough to take on the daunting task of writing the documentation for the Ytel API. Read on for his take on documentation for APIs and developers in today's market and why this piece is so important for a successful launch and digestion of any API. 

With message360° and its correlating API documentation, we offer a rounded service for consumers to take full advantage of, from getting initially set up all the way to using advanced functionality in the API. This all comes down to one guy, Wes Wise, who was brave enough to take on the daunting task of writing the documentation for message360°. Read on for his take on documentation for APIs and developers in today's market and why this piece is so important for a successful launch and digestion of any API. 

 

Documentation plays a central role in the way an API is perceived by developers. Poor documentation is often a sign of a badly maintained API — one that developers will try to avoid at all costs. The more you focus your API documentation on the developers, the more it will build their confidence and improve their experience, according to this article.

Let's begin with our Q&A with Wes Wise:

Q: What is the main purpose of the documentation?

 Wes Wise: The API had reached a level of maturity that required revising the documentation for a few reasons.  For one, the documentation on the technical side contained organizational issues, incorrect code samples, or missing information. A second reason involved marketing. On the marketing side, the API is described and advertised as being divided into four communication channels. This structural organization was missing from the documentation side of the API. In order to be consistent, we needed to bridge this gap. Finally, new features were being implemented for the API. These features needed to be added to the documentation eventually so it was imperative to correct the API of errors and organizational issues while adding documentation for the new features.

Q: How will users of the API find it useful?

WW: Hopefully, Ytel API users will gain an understanding of the API’s structure, functionality, and abilities by reading through the documentation. An emphasis on finding information quickly was integral in rewriting the documentation so that users can find what is needed and easily.

Q: What approach did you take in tackling the Ytel API rewrite?

WW: When I started to begin the documentation rewrite, I studied well-known and well-documented APIs in the tech space. Some of the APIs that I reviewed included Twitter and Facebook. These APIs have evolved and matured with a large developer following. I wanted the Ytel API to have similarities to the aforementioned APIs, but also wanted to include additional technical information that is necessary in understanding the API.

Q: How will employees find it useful?

WW: A properly documented API benefits internal employees just as much as it does for end users. Marketing and sales departments can use the API to summarize its organization and terminology to potential customers and possible partnerships. Developers, of course, use the API as a reference while building tools or any projects. At Ytel, it's valuable for all employees to be familiar with the API and know how to find necessary information.

Q: What makes API Documentation strong?

WW: First and foremost, API documentation must be organized into a format that allows its readers to find information as quickly as possible. Developers want to find resource URLs, parameter lists, and code samples quickly. Stakeholders want to understand the API’s capabilities, organization, and benefits.

A well-documented API should be consistent throughout its entire length. Consistency includes the content/material; how the content is organized and written. Consistency also includes frontend styling such as CSS, typeface, and choice of colors. Lastly, API documentation needs maintenance. The API itself will continue to evolve and change as features are added and underlying implementation adjustments are made. With the API changes, the documentation for the API must be updated to reflect said changes.  

Q: Why was the API documented by hand instead of using a Specification Format (Open API/Swagger, RAML, API Blueprint)?

WW: API Specification formats are great for documenting API resources. APIs are defined in human-readable formats, such as YAML and Markup which makes it easy to read, write, and to create third-party tools that can parse these files. The number of tools surrounding any of these API Specs is constantly growing.

However, these API specification formats have limitations. A major limitation for the Ytel API is the requirement for providing technical details about the entire API and the API’s organization. We needed a way to insert details into the API. It is not enough to just specify a resource with its url, parameters, and expected results. We needed to state what limitations, caveats, gotchas, and general information that developers needed to know.  We needed the how, what, and why for the API.

Additionally, we needed the ability to organize the API a certain way. API specifications allow adding tags or filters to each resource definition. This is fine if the API is small but falls short for larger APIs. Ytel's API contains a decent amount of functionality: resources are grouped by communication channels with some resources that work independently from one another. To achieve a common workflow, a developer may have to call multiple resources to complete a workflow.  For example, a phone number must be purchased (one resource call) before sending a text message or initiating a voice call (another resource call), and then the phone number must be capable of sending SMS or voice messages. This is the nitty-gritty details that were required to be added into the API documentation.

 Q: If the API doesn’t use an API Specification format, do you dislike them or see less value in them?

WW: API Specification formats have their place. I have been following their maturity for several years now, and the number of tools that are created around these specifications is growing. There are tools, support, and a community around these specifications. That’s great.  But for an API like Ytel's, we needed a custom approach.

In fact, the the Ytel API is already defined in the OpenAPI/Swagger specification separately from the main API documentation. This specification is used internally in case the API needs to be generated as a backup. By defining the API in a specification, this enables Ytel to take advantage of third-party tools that parse these specifications.

Documentation Writing Recommendations:

  • Don't rush the process. Wes wrote the doc by hand in Google docs, then converted it to HTML and styling... a process that took more than three months when it was all said and done.
  • Ask for feedback from your team throughout the process. Multiple sets of eyes should be looking at this doc and providing the author with valuable feedback.
  • Be prepared for updates, because they will come. As the API gets feature and system updates, its documentation will need the cooresponding updates, too. Plan accordingly. 

Interested in checking out the Ytel API and its correlating documentation? Click below to begin expoloring the API and let's see what you come up with!

New Call-to-action

 

Subscribe now to receive relevant and informative content to your inbox!

About The Author

Wes Wise, Ytel

Follow me on Linkedin

With a knack for technical writing and a focus on front-end development, Wes works on a variety of Engineering and Marketing projects at Ytel. As an UI/UX developer, he’s constantly following design trends, principles, and frameworks to implement the best solution for the task at hand.


Like this post? Share your thoughts

New call-to-action