The Use of Symbology in API Documentation

What is the role of symbology in API Documentation?

Sep 13, 2024

Before we invented writing we used symbols to communicate. Symbology is inherently connected to who we are as humans. Everything is a symbol. Every symbol is a message. How can API documentation benefit from the use of symbols? What can we, as readers, learn more—or better—if we consume symbols instead of just words?

This article is brought to you with the help of our supporter, Scalar.
Scalar is a suite of powerful & customizable developer tools to help you at all stages of API development. Create beautiful API Documentation in a notion-like editing experience.

Try Scalar for free!

I was recently involved in a discussion about using the padlock symbol in API documentation. The author, Oscar Islas, began by explaining how we use the asterisk symbol to convey that something is required. He proposed we use "a closed padlock in the description of a field to indicate that it must be encrypted." This idea, which at first feels simple, can have profound implications. And it made me think more about the topic and put it into writing.

At first, I hadn't given too much thought about symbols. Even less about their relationship to API documentation. But then, I started noticing how some API tools and more generic software already use symbols. The Swagger Editor by SmartBear, for example, uses the padlock whenever you need to provide authorization details. The Google Chrome browser also uses the padlock. However, in this case, its use is to show the connection to the Website you're viewing is secure. Using symbols in software isn't new. In fact, most applications rely on symbols to provide shorthand information to users.

Application menus and buttons use symbols as "calls for action." By seeing well-known symbols, users understand what to expect when they click a button. Some of those symbols aren't a representation of reality, though. Take, for instance, the symbol that most applications use to represent the "Save" action. It's a floppy disk. If you don't know what a floppy disk is, don't worry. Most people haven't used one since the early 2000s. What happened is that the symbol itself became a synonym for what it originally represented. So, users don't associate it with a real object but instead with its own meaning.

The padlock, on the other hand, still has a connotation with a real-life object that provides security. So, using an image of a padlock is a good idea if what you want to convey is a sense of security. Now, should we use it mixed with text as part of documentation? Or, more broadly speaking, should we mix text and symbols at all? We're already doing it all the time with emojis. Yes, those little symbols you use to express emotions. In most cases, people use smileys, but there are limitless options.

So, back to the idea that prompted me to write this article. How would you feel about seeing a padlock in API documentation? My feeling is that it can help consumers better understand the context of certain areas of the documentation. If the meaning of the symbol is not ambiguous. In the case of an emoji, for instance, there's no ambiguity in showing a smiley (🙂) because its meaning is universal—or, perhaps, I think it is. However, a padlock (🔒) can have different meanings in different contexts. It can mean that something is locked and not accessible, so you need authorization. But it can also mean that the contents of what you're consuming are secure and probably encrypted.

In summary, the idea of using a padlock symbol in API documentation is something I see as positive. However, you should align the meaning of the symbol with something readers are already familiar with. Otherwise, you're going to create confusion. Similarly, using any other symbol can be interesting if its meaning is widely understood by the audience.