Why I Don’t Like “Try It”

by Robert Delwood, a Lead API Documentation Writer

There has been a renaissance of API documentation tools in recent years. I like that trend. Our tools had been scarce and little attention was paid to this. We’re finally getting them. However, it doesn’t mean we’re getting the right tools. It’s hard to say what the right tools are. There’s still tool evolution going on.

What I can say now is that there are some trends I don’t like. And the Try It feature is one of those.

Try It is a capability built in to some API documentation rendering tools that allows users to make the call from the page. That is, clients can literally try it right then and there. It’s hard to imagine not liking it.

The Try It and code block items.

#1 The language bar. Selects the language the code block displays.
#2 The code block. The code for calling the request.
#3 Not directly related but the most valuable screen space is taken by a call history list? Egads, get rid of this immediately.
#4 Again, not related but I can’t resist. What is it this Note doing here? If there’s a restriction for a parameter, it’s mention belongs in it’s parameter description, not floating around in space. This is the first example that the writer is thinking like technical writer and not a developer. A developer goes directly to what they’re looking for by a search, and specifically the browser's search. That means they’re not going to even see this note. Here, it just takes up screen space, and makes clients look in two places for information. Besides, if a parameter doesn’t work, developers need to fix it, and writers either leave it out entirely or describe it like “Not applicable.”

As another aside, don’t use Notes. They interrupt reading flow. And why is that sentence any more or less important than any other sentence? In a way, everything can be a note, and if everything is a note, then nothing is a note. Not unless their next action detonates an explosive device or deletes an entire database. But I digress.

Restated more accurately, clients can attempt to literally try it right then and there. The concept is good, the execution is not. So much so, the documentation is better off without Try Its.

Not all calls are simple

When I see people advocating or demonstrating Try Its, it’s always only with simple calls. Calls with few or no parameters, and return few or no fields. That makes me suspicious in that the presenters either are not showing me the complicated calls, which makes this misleading, or they themselves don’t know, which makes this untested.

Regardless, the presenters aren’t thinking like developers. They’re thinking like technical writers trying to get a task done. They’re not testing the calls thoroughly. And they’re definitely not testing them in the same workflow developers would.

There’s more to making calls than many think. By not understanding that, at best, writers are giving developers tools they’re not going to use. At worst, writers are them giving developers tools that’s going to waste their time. It’ll cost developers time and effort, and it’ll cost your company reputation.

The fact is, calls get complicated quickly.

Lots of parameters

There may be lots of parameters. Many writers and PMs think in terms of simple calls. In truth, calls often requiring five, ten, twenty, or even 100 or more parameters are not uncommon. For instance, a grocery delivery service might require the complete list of groceries, and that can get up to several hundred parameters. These all may be required to determine volume needed, to validate the delivery address and eligibility, if there are cold or fragile items that need special handling, any illegal items, out of stock items, and so on. Even with only five parameter this starts to get complicated.

Time sensitive parameters

Some parameters represent time sensitive values. For instance, an expiration field may require at least the current time of day or later. That means this value has to be reset every time the call is made. This is a serious inconvenience to developers.

Can’t save parameters

As a corollary with having to add parameters each time, Try Its can’t save parameters. This shallow design means that values don’t persist from session to session. Worse yet, and this seems to be common, it doesn’t even save when you leave that page. Coming back means the values have to be entered again. This can be infuriating with even the fewest of parameters, or with complicated ones like UUIDs or GUIDs.

It’s not how developers use them

Ultimately, the most important reason not to use Try Its is that’s not how developers use them. The goal of API guides is make it easy on clients. So, how do developers use testing tools?

They run multiple times

Developers are crafting searches, experimenting with parameter values, trying to match output with their expectations, understanding how inputs work to predict output, rerunning them to see the exact output structure, or figuring out parameter formats. This means they’re running it dozens of times. They’re doing their homework ahead of time, perhaps debugging, and getting the HTTP call values right. Only then will they paste into their code.

For example, take the case of crafting searches. Writers would test the call in a superficial way. They would try it once or twice, perhaps even with different values, to see only if the call completes with a 200 and that all the response fields are present. They may get errors incidentally but few intentionally set out to cause an error. Errors are a valid testing point. Developers are going to get errors, so writer need to anticipate that. Nonetheless, they think that testing may be good enough for documentation. But it’s not good enough if you want great documentation.

Developers craft searches to get specific results, since they’re usually looking for something specific. The best analogy I can make is if you learned or use SQL. Chance are, you didn’t craft the search on the first attempt. It took several if not many attempts. Again, writers tend to think about one parameter, a search call using only the name field perhaps. What if there are 30 available fields, not an uncommon case, and the developer has to find the right combination of fields and values?

Given the expanse and nuances of searches, this may take literally dozens of attempts. Therefore, one unsaid requirement of the mechanics of crafting an expression is that adding different values each time is that it must be simple and convenient. Developers don’t want to spend time crafting searches, it’s unavoidable at times. They definitely don’t want to spend time figuring out how to simply change values. Since writers don’t make the same call 20 times in a row with different values, they would not be aware of this requirement.

Code blocks are bad

Many of these editors have a feature that show how to run the call from different languages, such as cURL or Python. Again, it’s hard to imagine not liking this. We think that developers like it. Copy and paste? All the code is in one place? Right? The problem is again it’s not how developers use them.

· First, making a REST call in an application is something that happens many times. The technical term for it is “a lot.” That means, developers are going to write one function, and just call that function each time. They’d pass in the URL and bodies as parameters to the function. They would use that code block example at most only once.

· Second, they probably wouldn’t use it all. They likely have their own preferences in coding and standards. That means, they’re going to use their code regardless. There’s probably six ways to do everything in every language, especially HTTP calls. For instance, in .NET C#, REST calls may be made with the popular RestSharp library or the built-in HttpClient library. What if they’re using a language Try It doesn’t support. Then we are just wasting screen space. Besides, we shouldn’t be advocating a specific language. It’s not a mandate for API documentation and the clients can do their language so much better than we ever can.

It’s unlikely the one way the code block is showing is the way they’re doing it. So, unless this is an inexperienced developers first time writing HTTP calls, it’s even more unlikely the code block will be used. On top of that, they’ve been doing it their way for years. They’re not going to change that now just because we display some code in the documentation. In addition, all they really need is the HTTP version of the call, and they use that as their parameters. Presenting multiple languages is actually an annoyance. This goes for cURL especially; it’s not considered a serious development method. Ironically, HTTP is sometimes not even a choice.

· Third, the code example in the editor isn’t good or efficient. Often, it doesn’t run the first time. Have you as the writer tested that code? That is, copied and pasted the block into a code project and then compiled or run it? If you have not, consider it as not providing tested documentation.

· Fourth, the code examples tend to be incomplete. It can rarely be used when you first get to the page because none of the fields are included. The client actually has to add the fields themselves for those values to display in the code example. The problem is that some editors don’t allow clients to add the fields directly to the code example, which would have been a decided advantage. They have to add the value through a field description, typically in the middle column of the page. That means they have to do a lot of scrolling, clicking, or digging around. They almost have to learn the call first, to know what the fields are, which ones are required, and their formats.

If writers had to include code blocks, what would make them useful? A number of cases. It’s too bad the displayed default case isn’t one of the following.

1. Provide a common case, perhaps the simplest that can succeed, so that clients can copy and paste reasonable code. They’ll know which values to change.
2. A case including all the required fields. Developers wouldn’t have to figure that out on their own. They just want to know which fields they need. Really, that’s all they want.
3. A case including all the fields. Unused ones may be marked as null.

Code blocks are not an entirely bad feature. They just should not use prime screen real estate. Move it to another place, such as displaying it from a menu item. It’d be there if someone needs it but mecrifully out of sight for the rest of us.

Why we’re not being told

If these features are so bad, why don’t writers hear about this more, or developers complain? For the simple reason that developers don’t care. They don’t use Try Its. Why would they complain? That means, writers can’t rely on getting feedback or assume that no news is good news.

We’re delivering incomplete products

We’re delivering features we should know developers will never use. It’s the “we should know” part that is disturbing. We’re in a developer’s world, writing to developers about development. It stands to reason we need to communicate with them in their terms. And we’re not. So, why is it writers are missing this? It’s because writers haven’t completed their mission. There’s two important tests.

1. Have you tested each call with Postman? If you have not, then it’s untested documentation. In a way, writers are just guessing. This would never be allowed in technical writing.
2. Have you written an application based on your documentation? This is called dogfood. Use your document to write an application but using only included facts. Use literally what’s written, and if it’s not there, you can’t use it. This will show a few things.

a. The documentation’s strengths and weaknesses. This is about the content. By using it yourself, you will know which descriptions are missing, incomplete, or ambiguous.

b. The documentation’s usability's not been tested. This is about the mechanics of using the documentation. That is, to see how easy or difficult it is for developers to find information, or copy and paste from it.

For example, ReadMe is among the worse, if not the worse, documentation platforms. It’s pretty to look at and it seems useful when viewed by writers and PMs. It’s bad because it’s not how developers use documentation. Finding or getting information is next to impossible from the developer’s perspective, there’s too much clicking, values don’t persist from session to session, or even page to page, and it’s difficult to test a call other the most trivial ones, and so on.

Workarounds

There are plenty of workarounds for Try Its. I’ll focus on Postman as a typical, but not the only, solution. Postman is a REST development and test tool. A reasonable alternative, as an example, to Try It is the Run in Postman button. It’s a button add-in for your API page. It brings up a Postman collection specifically to the active call. They offer 30 languages code blocks. Postman is going to do everything better than any company writing their own Try Its.

Postman solves every objection I have to Try It.

· 90% of REST developers have it installed. Access is not a problem.
· It’s already familiar with developers. Nothing new to learn.
· It’s free and is a proven industry standard.
· Parameters can be directly entered. Changing values is easy.
· Developers can save requests, including for different formats. You don’t think developers aren’t going to come back and run the call later?
· Parameters can be saved, again, for running again later.
· We writers can write the calls ahead of time for them using collection files.
· Placeholders or variables may be used for parameters or endpoint components. This allows developers to define a value once to reuse it multiple times.
· Outputs can be saved, for later reference or documentation. Sometimes developers just want to see the response field.
· JavaScript can be used for scripting. Developers can generate or calculate values, pass values to other calls, put in debugging comments, or anything else developers can imagine.

Conclusion

So, if developers aren’t going to use Try Its, what harm is there for including them? They can just ignore them, right? Perhaps, but there’s more to it.

It takes up valuable screen real estate (the right corner above the fold). Writers need to optimize the developer experience, even to the point of minimizing eye movements. Make it easy to find details. That space could be used more productively.

We “should know” but we don’t. This segues into the real reason. It demonstrates that writers don’t know the developer experience. Let’s be blunt. We’re delivering documentation suites that have not been tested properly, calls that are unlikely to have been tested, and tools developers don’t use. Not understanding these issues is the fundamental reason writers also need developer experience. Writers simply can’t empathize with own audiences, which means we supplying developers with inadequate and incomplete tools and documentation. This is a real concern.

This is not a condemnation. Quite the opposite. API documentation writers need to empathize with developers. Writers do this by treating this as a craft, learn a little about development each day, and move slowly along the experience spectrum towards the developer’s end. Learn a language. It doesn’t matter which one. Java, JavaScript, to DOS batch commands, UNIX command line programming, Word macros, Python, or even AutoHotKey*. All of these have programming concepts and that’s what matters. Learn about them, which requires using an API guide, craft statements, and debug them is at the heart of the matter.

===

AutoHotKey (https://www.autohotkey.com) is a scripting language primarily used for automating tasks, for now, on Windows computers. It’s can be as simple as assigning a key to insert text, such as CTL-1 for your name. That alone is convenient.

But it’s also a script and has a programmatic aspect such as conditional statements and looping. Learning that has direct application to empathizing with client developers.

In addition, to learn it, you have to use their API guide. That means you can get to experience using others’ API guides to see what you like, dislike, would change for the better, not do at all, and what’s helpful to you learning. Guaranteed you will see the value with having copious examples. I predict there are cases copying the example is enough and you won’t even read the text. That’s the exact feeling you want your client developers to have, too.