The design of API documentation. Thomas Bohm’s interview with Joanna… | by Joanna Suau | Jan, 2022


Such an approach also ensures that your traffic goes through the most optimal route, increasing communication speed and with it the entire user experience. And this is something that is very easy to overlook when creating API documentation; developers are not only the target audience, but also users who are striving for a seamless user journey. Another good rule of thumb when it comes to API reference content strategy is making sure your code samples are kept up-to-date, work, and are easy to copy and paste, because that’s exactly why they’re there. To me personally, a good API reference would always have a copy button that would copy the entire code sample with just one click, removing the possibility of not grabbing the entire sample when trying to do the same thing manually. It’s a fairly common feature nowadays, but it certainly deserves a call-out.

TB: Could you tell me more about how you provided documentation designed to cater for various target audiences (developers, end-users, system admins, sales team, and so on) when you worked at Pierbridge (a leading provider of enterprise parcel shipping software), and how you were responsible for creating and maintaining company-wide style guides at Moltin (an API-first digital commerce solution, now known as Elastic Path)?

JS: When I worked at Pierbridge, their documentation was not open source, so it was quite straightforward to split the content per persona, and have separate sections indexed for different use cases. You had to make sure that different audiences knew where to find content designed specifically for them, and that the content was single-sourced, so you didn’t have to copy and paste the same information into multiple places.

At Pierbridge, we had a very good authoring tool called Flare (2021), that was very well designed for that type of authoring. It had a great indexing feature which worked really well in combination with their search capability. You could also add conditional tags to your content, so that later on, when generating an output, you could choose which content to include and which to exclude, so as to adapt it to different personas, products, and so on.

Moltin’s documentation was a bit challenging to maintain because we had a lot of authoring platforms that we used for various content types. Creating a style guide that would cater for different audiences, for the different tools we used, and for the different writers we had (developers, marketeers, technical authors, copywriters) was a real challenge. We had to design a set of conventions on how to document various aspects of the API — how to provide code samples, how to describe the code, how to describe any user interface (UI) elements that come into play, which words to use to describe the API from the marketing point of view, and so on. Our style guide turned out to be a set of templates for the writers to use. Each template would cater for different content types, like a blog post, a user guide, or a use case. We also put together a list of the most commonly used words and a set of grammar rules to help us have a consistent voice. The simplest example would be that we would all consistently use the Oxford comma and would never use camel cases in titles or headers.

TB: API design, writing, updating, testing and bug fixing seem to take an enormous amount of time and effort. APIs seem like one of the ultimate document design (Schriver, 1997) challenges, they contain a mass of information and a very wide-range of information types. What do you know about the staff numbers, workforce, and the time it takes to develop an API?

JS: The short answer here would be there is never enough resources or enough time to write a perfect API reference. Joking aside, I’d say that it would depend on how complicated the API is, rather than how many developers are working on it. Another question is who’s doing the QA (quality assurance), developers or a dedicated team of testers? Ideally, there would be a separate development team working on the API, and then the API would be released in stages for the testers and writers to test and document it. Then, all teams would engage in a review process to make sure the code samples are syntactically correct, and the content is technically accurate. Typically, you have developers doing everything, from working on APIs to writing documentation. If you are lucky enough to have a writer on the team, the writer would typically go into the file that’s already been written and edit the content to make it more presentable. Companies nowadays are starting to realise that this is not an ideal situation, and technical writers who specialise in documenting APIs are getting noticed. You can see the shift in the job market, as more and more technical writing jobs now requires to be familiar with APIs and ways of documenting them. A research done by Cherryleaf (2003) measured the ideal ratio of technical authors to the number of developers. According to them, the ideal ratio was a ratio of 12 developers per writer for organisations with fewer than 500 developers and where developers do not produce user assistance documentation. As for how much time it takes to develop an API, it all depends on what your plan is. Are you planning to have your prototype deployed and documented as an MVP (minimal viable product) to build upon that with time; or would you rather go for a more sophisticated architecture, taking into consideration all crucial aspects of a good software: reliability, security, data processing speed? In recent years, we have observed a boom in startups. This shows that developers tend to deploy an MVP to build upon. Typically, they would provide an opensource version of the API hosted on a collaboration platform like GitHub, so that other developers that are interested in using it can contribute to its development. Then, as the product matures and is improved upon, they start thinking about some billing plan to capitalise on that API.

TB: Research by Waller (1979) makes the following observations on reading style strategies: browse, skim/preview, search/scan, intense study, review. Furthermore, Waller (1982), when referring to the relevant associated issues of access structures, states “The designer can use spatial and graphic means — rules, borders, tints, type variations, and so on — to assign qualities to and to display relationships between different components of the text. To put it another way, she/he can diagram the text.” So, in other words: text and layout design, for and leading to instruction, explanation and understanding. APIs need to be quickto-load, easy-to-use, understandable, and actionable (Whiteside, 2018). According to Sless (2004), the attributes and characteristics of successful public documents typically are: attributes that encourage reading (credible, respectful, attractive, physically appropriate, socially appropriate) and attributes that sustain reading (easy-to-use, efficient, productive). Sless also mentions (Sless, 1989; Sless, 1990; Sless, 2017) that users dance between elements, signs, symbols, meanings, and things, as they try to use and interact with graphic communication. In short, for Sless, “interfaces should work like a good theatre performance” (Sless, 1990). There is much that goes on in graphic communication that is invisible (Luna, 2021). Could you mention any aspects which you have identified, or which have been mentioned by users, that are critical core tasks? And where do you think typical APIs do not work well or fail (trip-up)?

JS: To answer your last question about scenarios where APIs may not be the best solution to implement, there’s a bunch of technology that has originated using different protocols and data exchange processes which is now slowly trying to reach the API world. A good example is the company I worked for, OpenMarket, and the company that has recently acquired it, Infobip. Both companies provide mobile networking software which allows mobile devices to communicate with each other. SMS (short message service) and MMS (multimedia messaging service) have been with us for a long time now, and they haven’t started as REST (Representational State Transfer) APIs. And so, SMS and MMS APIs are still considered quite new technology. Their main advantage is the speed with which they exchange data, but the main drawback is that there’s a limit to how much data you can send reliably; so, if a company wants to send a lot of messages on a regular basis, they may encounter some traffic issues using an API-based solution. A lot of companies still use traditional data exchange protocols, such as SMPP (short message peer-to-peer) for SMS or MM7 for MMS because it’s familiar and reliable, and most importantly, because it uses binary files which are great for storing and exchanging large amounts of data. The disadvantage of such old systems is that they are complex to implement and maintain, so they’re not cheap. APIs are more cost effective as they’re easy to implement, build upon, and maintain.

TB: It is widely assumed that “People do not read on the web” (Nielsen, 2008). I feel that what they actually mean is that people do not read large amounts of text or lengthy articles on their desktop monitor. Reading from a smartphone is slightly different from reading from a computer monitor, because it allows for reading in different environments and contexts, for instance, when the person has a lot of time to read. So, if people do not read large amounts of text on a desktop monitor, most API documentation, which is very lengthy and complex, probably works better in the area of quick look-up access, where people can find modules and specific things they need to know and implement. In Suau (2020), you say that “API documentation is a necessary evil,” which is a great point; and Mark Barratt (2009) says “OK, all else *has* failed so it’s time to read the documentation.” There seems to be no getting away from providing API documentation. If people do not know how to use the programming language or system, and cannot work it out, or get a fix to their problem, they would probably go and use another system. So, from this point of view, it seems that APIs are not only essential, but also critical to the uptake and success of application systems? Would you agree?

JS: Very good observation. People turn to online guides to solve a specific problem they have. They don’t necessarily want to read a description of all UI elements that a particular piece of software has. They want to find a solution as fast as possible. There’s still some variety in the way people will reach that piece of content though. Some will use search, and some will use a table of contents. So, it’s up to a technical author or instructional designer to come up with as many paths to the same piece of valuable content as possible, so that it can be easily reached by everybody. You never know how your reader will arrive at a topic. It may be the very first thing they are reading, so you don’t want to confuse them right at the beginning of their reading journey, even though for you it’s the middle of a larger piece that you wrote. A number of content strategies can be used here. Ted Baker (2011) wrote a really good summary of how to approach online content, called Every page is page one, where he explains how vital it is to explain the context for each topic you create. So, you basically treat every topic as a separate standalone article, with all your typical necessary bits like introduction, purpose, audience, body, summary. This approach is based on one of the most popular content strategies called ‘topic-based writing.’ It has several advantages to the user and to the writer. A user will always know where they are, and why they’re reading what they’re reading, because it’s all there in the introduction. The writer has at their disposal a number of self-contained topics that they can reuse in different places, without the fear that they will seem out of context. API documentation is a bit different. Although some parts of it are standalone (endpoints, error codes, and so on), and can be reused and moved around, there’s a certain hierarchy to how you interact with an API. For instance, you cannot use the API unless you authenticate your endpoints, so that would probably be the very first thing you want to read about as a developer. This is why it is important for a technical writer to know how an API is used by developers before they document it; and why it is so important to collaborate closely with the development team to create the best possible user journey while maintaining the contextual integrity any technical author strives for.

TB: Schriver (1997, p. 138) states “The onset of the computer revolution promotes technical and professional writing teachers to develop courses on computer documentation.” The book also contains the feedback given by users in response to a questionnaire on how consumers value instruction manuals, as well as data on how document designers rated hardcopy and online versions of manuals (Schriver, 1997, p. 223, 387). What do you think are the positives and negatives of printed and electronic APIs? Is there any place for printed API documentation?

JS: I think the only place for an API reference is online. API uses web resources to communicate with databases, servers, other APIs. So, having documentation in a printed format would be highly inconvenient as APIs don’t belong to this world. Also, from a content management point of view, because APIs are dynamic and developers who work on them add a lot of new features with every deployment; a printed output would be very hard to maintain, as you’d have to reprint it every so often. And I’m not even mentioning the ecological and economic burden of using a printer and producing tons of paper! To have printed APIs will also defeat one of its core purposes, which is to allow a developer to figure out how the API works by using provided code samples. It would be too cumbersome for a developer to type in all the code, just for testing purposes. An API reference must live online; moreover, I’d say that nowadays an API reference must also be interactive, to allow a developer to get what they need in the most efficient way.

TB: Part of the role of information design is to test and measure how well API documentation works. How do you know that the API documentation is working well for people? And what measures do you have in place to deal with user feedback and remedy issues and bugs?

JS: End user documentation is very often used by your own colleagues from other departments, like sales, support, customer experience. The easiest way to check for usability is to encourage your colleagues to share their feedback and raise any issues as soon as they encounter them. Documentation issues and bugs like typos, invalid URLs, or missing images need to be dealt with immediately, as these should have been caught during your standard content QA (quality assurance) process prior to publishing. Bigger issues like user feedback should be carefully looked into and prioritised. Sometimes when you try to resolve one issue, others arise. For instance, imagine that a user came up with a more descriptive title for your article, which is great and looks like a quick fix. But now you need to think about all the changes this one little thing can trigger. If you change a title, you’ll also need to change the table of contents that lists it. Is the URL going to change? Is the article linked to from other places that need updating both the title and the URL? Apart from the content itself, and I exclusively speak of online content here, we should also measure how our users arrive at it. Nowadays, it’s quite easy and common to plug into the site where your content lives, a tool that tracks and reports the traffic. You can then tell which sites are the most popular ones, and which ones are not. You can also check what search terms were used to find specific articles, so that you can then adapt your content accordingly. If an important article, which you know users will most definitely benefit from reading, has few views, this means that most probably the article is buried too deeply in your current content and is overlooked. The easiest way to check this is to elevate the content and make it easily findable. If the location of the article is indeed the issue, your page views should now bounce up quite quickly. If not, you’ll need to figure out what other reasons there could be for the low number of views; maybe the language used in the article is too technical or complicated. The easiest way to test this would be to use a tool that analyses readability and suggests content changes based on that factor.

TB: HTML and CSS seem to work quite well, the basic principles of tags and classes .class {} is fairly straightforward and easy-to-learn. In recent years, we have had things like SCSS (a more sophisticated version of CSS), and JavaScript frameworks like Angular (2021); React (2021), and Vue.js (2021), which are essentially pre-built interactive website frameworks that seem to be gaining great popularity. Erik Spiekermann (a well-known typeface and information designer) said that “You have to learn if not to code at least to appreciate code, to understand code. Because code is what nuts and bolts were a hundred years ago” (Spiekermann, 2016). How do you see these basic and foundational information programming languages and technologies changing in the future, and what may they look like in the year 2040 or 2060, if they are still being used?

JS: I definitely agree with Spiekermann. Understanding the principles of coding is quite important if you want to understand how a developer looks at the code and works with it. Without that knowledge, you will never be able to fully cater for this particular audience. If you have to document a user interface, you look at how it works and put yourself in the shoes of a typical user. Similarly, if you need to document code, you will have to at least understand how it’s going to be used by other developers, and what would be their typical pain points that you could solve with your documentation. I wouldn’t go as far as learning how to use a framework, frameworks come and go (Allen, 2018). Back in 2013, the hottest and most fashionable framework was Ember (2021). Nowadays, hardly anybody works with Ember, because other frameworks have gained in popularity and have a bigger developer community to help with troubleshooting. So, instead of learning about something temporary, it would be more beneficial to familiarise yourself with some basic computer science concepts, or to do a beginner’s front-end developer course, to learn about the concepts anchored in this particular context.

TB: I have felt for a few years now, that the graphic communication design industry is in the golden era of accessibility and usability (Bohm, 2018; Diamond et al., 2020). Since about 2010, the work on and interest in accessibility, usability and inclusiveness have been very notable. A website design created after about 2016, is required to be, and assumed to be accessible, and has by default, significant accessibility input and design. In 2021, to supply a website design that has had no accessibility thought or design, seems (nicely) a ridiculous scenario. You have also written about making documentation accessible (Suau, 2018). Do you feel it could easily be a lot worse than it is now, and we could easily not be in the strong position we are in now?

JS: I agree 100% — we live in the golden era of a customer-centric design. It has a lot to do with accessibility and inclusiveness, but I fear we are still not doing enough. I don’t know about your experience, but from what I’ve observed over the years, any MVP (minimal viable product) will focus on accessibility only as a nice-have not a must-have. It’s not a blocker, if your website uses an old front-end library like Bootstrap (Bootstrap, 2021) v4 or even v3, which is not very friendly when navigating with a keyboard or using a screen reader. Version 5, which was only released in May 2021, so it’s still fresh news, is more focused on accessibility and it is much more robust in terms of the CSS styles you can apply for screen readers. Fortunately, as well as releasing their more friendly version, Bootstrap recognises where they’re falling short and is working hard on improving accessibility, which is very commendable of them.

TB: At the moment, is anyone doing any research or work that you really admire? Who has had an impact on your work?

JS: I really like a blog written by a fellow technical author from the U.S.A., Tom Johnson. He advocates the importance of good developer-oriented documentation. He’s published a free and really comprehensive course on how to write a good API reference, which he keeps updating, so the content never gets stale. It’s a good resource to learn the basics, but also to go back to for the most up-to-date content practices. I’ve also been following the UX Collective. It is a group of technical authors, web developers, designers, UX researchers — basically everyone who contributes in any way to a frontend, and they share their stories, thoughts, and experience on user journey, visual and product design, and UX (user experience).

TB: Is there anything else you would like to say about API documentation, or about your experience working on API documentation, and how you think it might evolve in the future?

JS: As we’ve already mentioned, more and more companies include an API in their technology stack (combination of programming languages, frameworks, and tools that developers use to build a web or mobile app). More and more, successful start-ups compete against big industries, with their state-of-the-art, fast APIs and amazing documentation. So, I think there’s a huge shift in the API industry’s mindset. Documentation is no longer considered just a reference of endpoints a developer can implement in their project. It is an advertisement for a technology that should be appealing to both developers and business decision makers alike. It’s about a seamless and eye-catching user journey, as well as informative documentation and easy-to-implement features.

TB: Thanks Joanna, thanks for speaking to me, much appreciated.

Allen, I. (2018). The brutal lifecycle of JavaScript frameworks.

Baker, T. (2011). Every page is page one.

Cherryleaf. (2003). How many technical writers should we have in our organization?

Diamond, A., Hazell, B., & Stevens, L. (2020, August 27). Content design.

Hiller, C., Hinton, S., Hussein, A., & Santo, J. (Host). (2020, November 19). How to design a great API [Audio podcast]. JS Party — episode #154.

Luna, P. (2021). Paul Luna on the typographer’s task [Video].

Nielsen, J. (2008). How little do users read?

Santos, W. (2019). APIs show faster growth rate in 2019 than previous years.

Sless, D. (1990). The theatre of interface. Communication News, 19.

Sless, D. (2004). Designing public documents. Information Design Journal, 12(1).

Sless, D. (2017). From semiotics to choreography. Information Design Journal, 23(2).

Spiekermann, E. (2016, January 15). Erik Spiekermann — on my Om. Om Malik blog.

Suau, J. (2018). Accessibility in online documentation. Communicator, 2018(4, Winter).

Suau, J. (2020). Support, customer experience and docs. Communicator, 2020(3, Autumn).

Whiteside, K. (2018, February 2). How to carry out a plain language edit.

Source link

Leave a reply

Please enter your comment!
Please enter your name here