A Review of the ShipEngine Docs

Have you ever had to integrate with a third-party service or software at work or on a personal project? If so, my guess is that the first place that you went was the documentation page. Other than the actual software or service itself, documentation is arguably one of the most important aspects of a project. I argue that a good docs page can make or break the success of a project. In many cases, documentation is the first thing a potential user or developer see’s. In this blog post, I will be taking a deep dive into the Address Validation documentation of the ShipEngine API. To help make this review process more comprehensive and understandable, I have defined a rubric that I will be using throughout the post. The rubric is as follows:

Findability

Even though every criterion in this rubric is important for having good docs, I still think findability is arguably the most important (if I can’t find the documentation, how am I suppose to use the documentation?).

• How difficult or easy is it to find the appropriate documentation?
• How difficult or easy is it to find other relevant pieces of documentation(i.e., code-snippets or implementation and use case examples)?

Clarity

The purpose of visiting the docs page should not be limited to understanding how to use the underlying service. Providing a clear description of why the product was built is an integral part of understanding how to use it. In addition, once you think you have found the documentation you are looking for, it is important that you clearly understand whether or not you’re in the right spot.

• Is the purpose of the software or service clearly defined?
• Does that clarity remain throughout the page?

Readability

If at any point I start to feel as if I'm reading the instruction manual for the lawnmower I just bought, I'm going to start scrolling and skipping over important information, or even worse, I'm going to go to Stack Overflow. If you have ever used an API or any technology with unengaging-hard-to-read docs, you know what I am talking about.

• Is the documentation engaging and readable?
• By the time I get to the bottom of the page, do I fully understand how to use the product? Or, do I immediately start googling and looking for answers to questions?

The Review

As a reader, it might be helpful to understand that I have used the address validation tool first hand in a side project of mine. So to make this review as accurate as possible, I'm going to walk through my thought process as a developer visiting the docs for the first time.

When initially landing on the ShipEngine docs page, you are presented with the various tools ShipEngine offers. From there, finding the address validation page is fairly straightforward.

Address validation ensures accurate addresses and can lead to reduced shipping costs by preventing address correction surcharges. ShipEngine cross references multiple databases to validate addresses and identify potential deliverability issues.

Upon opening the page, you are greeted with a brief overview of the product and a quick pitch on why you want to use it. This nails the clarity criteria on the head.

Moving on, you are very quickly given an example of how to make a request. It might just be my style of learning, but I am very biased towards a good example. To make life even easier, you can select between different languages, and it will adjust the implementation accordingly. This scores huge brownie points in the “not having to google” department.

The final part of the docs is where I have encountered the most friction. The example shown above is followed by a comprehensive list of the response status types and their meanings. The page then finishes by giving examples of each status in the form of their respective POST requests. My problem with this part of the docs does not involve the material provided but rather the lack of material. I kept finding myself looking for a way to actually test out each POST request to see what gets returned, but I couldn't find one.

Upon further investigation, the “API Reference” directory under the “Start Here” tab gives you a full rundown of exactly how to call each tool in then ShipEngine API. It even gives you the option to automatically open a postman collection containing an array of pre-built requests for each tool in the ShipEngine suite.

So here’s my question.

After navigating to the documentation landing page, why do users have the ability to search through the entire suite of tools if each tool’s individual documentation page doesn't contain any postman or testing functionality?

And while the initial documentation landing page does attempt to direct users to the “Start Here” tab, it’s still misleading given the multitude of options.

Furthermore, if a user were to access a tool's documentation directly from google (i.e., they google ShipEngine Address Validation), they would skip the landing page altogether and be taken directly to that specific tool's documentation. Thus, missing out on all the juicy postman collections.

My solutions

Either one would solve the problem.

1. Upon opening a tool’s documentation, be sure to call out the postman ShipEngine walkthrough.
2. Give users the ability to test each API tool in Postman from that tool’s documentation page.

Final Thoughts

Like I said before, documentation is arguably one of the most important aspects of a project. In a lot of cases, documentation is the first thing a potential user or developer see’s. While the Address Validation documentation has the foundation to be great, there remains some work to be done as far as findability is concerned. However, all things considered, the ShipEngine docs are very well made; with just a few organizational adjustments, I think they could be great!