I’ve been studying up on the writing in API Futures this week. Here are my recommended reads for technical writers or anyone who cares about APIs.

The future of APIs is (still) beginners

(Taylor Barnett-Torabi)

Thinking of beginners is always a good idea, because the beginning is where most of the pain is with using software. Getting customers to implement your API in the first place and to continue to use it depends on the ability to quickly and easily onboard new users.

That's why I agree, but Taylor has a lot more to say about the subject. Be sure to check out the article.

API lint levels

(Lorna Jane Mitchell)

Here's another piece that underscores the necessity of good documentation to the success of an API.

What is the meaning of this? Semantics is the key to successful API/AI integration

(David Biesack)

API Design Matters

What is the Meaning of This?

After 2023, “The Year of AI”, I’d be insulting my valued readers if I claimed that the biggest change in APIs in 2024 will be anything but AI related…. for me the question is how will AI impact APIs? I believe adding semantics (meaning) to APIs is the key to successful API/AI integration…

Read more

2 years ago · 4 likes · 1 comment · David Biesack

David has some intriguing thoughts about how AI and APIs will work together.

What The Latest API Job Market Data Predicts

(Matthew Reinbold)

Net API Notes

What The Latest API Job Market Data Predicts

I love me a good API industry survey. I appreciate the vendors and analysts who carefully craft these questions and share the aggregated answers from their customers with the rest of us, often for free. I always learn something. However, there's also something that has bugged me about this approach. When a tool vendor asks their customer base or social m…

Read more

2 years ago · 6 likes · 1 comment · Matthew Reinbold

Everyone loves an update on the API job market. This article is fascinating because it shows not only that "API jobs are everywhere," but that there are still more SOAP APIs than GraphQL APIs. Who knew? Check out the numerous interesting findings.

One trend to watch for in the future of APIs is a more intense focus on the customer experience.

A customer-first approach is the antidote for a majority of the issues (present and maybe also future) that API developers and users struggle with. The realities of business and software development tend to nudge outcomes in exactly the opposite direction, and where APIs are concerned, the documentation often makes the difference between a disappointing experience and a better one.

Here are the documentation factors that have an impact on usability.

Completeness

Documentation should include everything that users need to successfully adopt the API and continue to use it:

• Reference docs that cover every single parameter of every single endpoint, as well as topics like auth, error codes, and rate limiting.

• A get-started tutorial.

• Conceptual material that explains what the API is, the problem it solves, how it works, and what it can and can't do.

(I've written more about that starter set of docs, which I call minimum viable documentation.)

Ease of getting around

This category combines a couple of easily overlooked areas: navigation and search.

Navigation

• Are your reference docs (Swagger or the like) in a separate location from the rest of the documentation because they were difficult to integrate? If that's the case, reference documentation will be that much harder to find.

• Have you grouped the DevOps-related content together with the API reference, but without mixing in content intended for other users? Non-API docs clutter the user experience with unneeded information -- the folks who consume APIs provided by your product may be completely different from the end users who receive the data from your APIs. If so, keep the documentation sets completely separate.

• Is it possible to get from any page of your site to any other page within one or two clicks?

• Is the documentation organized so simply that users can guess where they need to go most of the time, even if they haven't been there before?

Search

• Can users search the complete content of your API-related docs from one search interface? (If they are searching API reference, can they search all the content, or just the headings and summaries? Some searches only seem adequate until you search for the name of a parameter that you remember using.)

• Is it possible to search only the documentation for the product I'm concerned about, as opposed to all the products and media that you own? Can I narrow the search to just the API docs I'm concerned about?

• If a search gives more than one page of results, is it possible to filter?

Effectiveness

Customers need to know when they look up documentation and code samples, they are getting information that will work. Assuring that the documentation leads to success depends on practices like hands-on testing by authors, running programmatic tests of code samples, and communication with customers (when possible) to verify that how-to articles cover all the necessary use cases.

API design

The usability of the API itself can be improved on two levels.

• The naming of properties and parameters. You're creating a taxonomy that should be understandable, consistent, and predictable for the end user. (There are numerous guides about the subject, online and in books. For example “The Design of Web APIs” by Arnaud Lauret.)

• The workflows (the pattern of requests) required by the API to complete a particular task.

A technical writer can make a significant contribution to API design by reviewing either of these design factors early in the process.

• Docs as Code is indeed the best tool for many situations, but there are other tools and other situations.

• Every tool has an ideal and proper use, and you should understand what tools were developed to do, even if you will never need them or don't want to use them.

• Don't assume that you have the wrong tools in your shop, even if there are things you don't like about them. The tool was most likely adopted by your group for important reasons.

• If you do find you have the wrong tools, remember that it's never the tool's fault. Your organization's needs might have changed, or your organization might not have a strong process for selecting tools. If the latter was an issue, proceed with caution and humility.

• You can adopt more than one tool or toolchain if you have two kinds of authors with drastically different needs.

• If you change tools, the ideal justification is a better customer experience and ease of use for the authors. If you don't see at least one of those benefits in a change, reconsider what you're doing.

• The right people should be working on each set of docs. Engineers can have a big impact by contributing to the reference docs (e.g. Swagger specs.), but some kinds of documentation are better if they're written by technical writers. When you decide who writes the documentation, ask who can produce the most helpful documentation for the customer, and ask who can produce it quickly.

In case you missed them, here are the previous articles from this series about toolchains.

Knowing your toolchain requirements prevents misery

A definition for Docs as Code

When Docs-as-Code is a big success, this is why

Anne Gentle: 'How do you keep your authors happy but also make sure your customer gets what they need?'

Toolchains have families

Last year I wrote about toolchains, and why you should consider the full toolchain when considering any new tool or component. (See Apples and oranges.)

If you're making changes, it also helps to consider toolchain families.

Every toolchain is different, but then again they often fall into familiar categories (or families). Each family exists because people were trying to solve a common problem, or to work in similar circumstances.

I like the idea of having a map of the toolchain family universe, because it gives me a view of all the options and why they exist.

If you're like me, you have favorites and you wouldn't choose to use certain toolchain families for documentation -- and yet, you've used most or all of them at some point.

More importantly, if you recognize that each toolchain family has been chosen for a reason, you won't make a misstep in choosing new tools -- because the tools that somebody chose for your organization's documentation before are clues about requirements that may still exist.

If you want to jettison a certain funky or seemingly old-fashioned tool, be sure that you understand why someone chose that tool in the first place and you will avoid a wrong turn in your tool usage.

Take a look the five most common toolchain families.

Anne Gentle has seen numerous changes in the documentation world since she wrote the first edition of “DOCS LIKE CODE.” She’s also made some observations about the things that don’t change.

How has docs as code changed since the first edition of the book?

A short bullet list of what has happened in five years:

• There are many more docs contributing guides.

• There are many more public examples as use cases to study.

• GitHub has an improved web interface for making updates.

• It’s easier to use Windows to work on docs-as-code.

• GitHub uses main for the default branch instead of master.

• GitHub has an easier file-based view for reviews.

• GitHub pricing changed.

• Read the Docs has grown a lot!

• Linters and inclusive language checks are more prevalent.

What were the other projects using?

 Sometimes it would be a wiki, sometimes it would be a video project…or maybe something like a CMS or…a pure metadata collection, or code examples.

Docs as Code seems to be the standard approach now.

In software for sure. In API documentation, definitely. Anywhere that there's a developer needed or a developer view needed, I think it has been become more of the default.

Are practices changing at all?

I think, people are really more sophisticated with the tooling around community contributions or GitHub itself has become more user-friendly. You know, you can actually make an edit in your web browser ­­– you don't even have to pull it down. Because that was the hardest starting point if somebody didn't already have an idea of what a development environment was…Now that people can just contribute with a web browser, that makes a world of difference.

What’s new in the Third Edition of “DOCS LIKE CODE”?

I hadn't really ever talked about linters previously, and I feel like people really get those especially if you're already in a CI/CD pipeline. They're already linting their code, probably, so adding an inclusive language linter in there makes total sense.

I hope we're at…a point where the testing with an AI is going to make more inclusive language.

We are already using AI to edit…autocorrect is an AI. Chat GPT is just autocorrect on steroids for words and paragraphs and sentences, right? I think Grammarly has already made me a better writer. And I think tools like Acrolinx are just amazing natural language processors.

Do you address developers differently from writers when you’re trying to bring them into a Docs as Code universe?

The Write The Docs community, the Read the Docs community, that is a bunch of developers who really cared about documentation. The founders wanted to set up really good CI/CD for their docs. And Python, I think, is a really doc-friendly, doc-centric developer Community.

 So, you know, developers take to it really well and actually prefer it. I've gone to, DevOps Days Austin and presented Docs as Code there, and they're all into it. If they had never heard of it before, they're very excited and they're just looking for the best practices: Do I put the docs with the source code, Do I put it into its own repo, What are the best static site generators?

But I think there’s the tools side and then there’s the people process. So if you really have a large community, there's a couple anti-behaviors. One would be start a big change but don't consult with any of the maintainers that they actually want it. So you could write a bunch and then not get your PR merged anyway, because it wasn't the direction they were thinking. So one of the best practices is open an issue. Hey, I'm thinking of doing this. What do y'all think?

You talk about your work at OpenStack docs in the book, and there’s a mention of some DocBook and other XML documentation (p. 29 in the second edition). Did you keep those docs around and have them maintained by technical writers?

That was more how we started out. But actually a couple years later, we moved all of the docs next to the code… You can do either model.…We took them into RST at that point.

At Rackspace, we had a tools team that had built this pretty sophisticated DocBook-plus-WADL implementation, so that’s why we were there. The original specification before openAPI specification, and before Swagger, was WADL.

The interesting thing was, I choose DocBook because Red Hat used it. It seemed like the best for a big open-source project. They all totally worked in DocBook – that was it right there. So just weighing it with like, well, who do I think will come help. Let's go with DocBook for now.

And then later you had more developers, which led to reStructuredText?

Yeah, we had more developer contributors, and that was awesome.

Do you have many cases where developers and technical writers collaborate, but with different markup and different editing tools? Or do you try to keep their toolchains the same?

I think the whole point of Docs as Code is to get developer tooling for writing. I talked to a tech writer once, that once they saw continuous integration (and) continuous deployment, they were like I won't ever be able to work another way again. This is the best way. Because you can write instead of build, build, build, you know?

At Cisco, I’m the Global Lead for Developer Experience, and I have tech writers, I have advocates, I have developer Community folks, and we enable 700 people at Cisco to work in our Docs as Code tool chain…I mean we're probably at like over 1,000 docs projects…And here's the thing…It could be a technical marketing person. It could be a product manager. It could be a tech writer. It could be an engineer. We see a lot. I mean 700 people.

Do you use the same tool set and the same markup language across all the projects?

Yeah, we use markdown, we try to stick with the GitHub-flavored markdown spec. And then openAPI is another format. They first started this continuous integration, Docs as Code project before I joined, so it's probably six or seven years old now, but they originally took in Markdown, XSMART, -- which was Cisco’s DITA, as I understand it – and HTML.

Would you say that you avoid DITA because you tend to work in organizations that need to get developers to contribute? If you worked with a lot of technical writers using DITA would you discourage it?

I don't even think we have teams that want XML or HTML.

Unless you're doing translations..DITA is more complicated than almost anyone needs.

You have tradeoffs in complexity for authors and output, so for specific requirements, you'd choose the right tool for the job. If you're going to make requirements and tools simpler for contributors, Markdown is the way to go since it doesn't require an XML editor/validator. As another example, if you're working with Python contributors, RST is the way to go.

Suppose you need DITA for requirements like translation. In that case, you should empower your contributors, whether tech writers or developers, with the tools and training they'd need to write with DITA in XML. I have yet to have a translation requirement at Cisco for developer docs, but for their large docs site, Cisco uses a specialization of DITA.

I love DITA for teaching topic typing. Telling contributors to write a concept, task, or reference helps many people understand technical writing better.

But for trying to get the most contributions from the most developer-y people just stick with markdown.

So what did I forget to ask you about?

I was reading a couple of your posts and I think something people could really use – and I might just post this – is a requirements template. I feel like people just choose Docs as Code because it's the latest thing, but you really have to go back and say well what do I need. Do I ever need PDF? Do I ever need the scenario of someone needs to read this on a plane or someone needs to read this in …an air-gapped situation?

How important are images, how important are tables? How important is localization?

if you need interactive docs it's a whole set of requirements, right? If you actually need code samples to work, that's a whole set of requirements.

So you kind of also have to do like: Critical, Nice to Have, Nice-But-Not-Required.

You’re suggesting a checklist that walks people through the important questions because most people won't think of all the requirements unless someone asks?

And you do it from an authoring standpoint and you also do it from a customer standpoint, right? So how do you keep your authors happy but also make sure your customer gets what they need.

Did you have examples of a requirements template that you could share?

A requirements doc example was in the Write the Docs newsletter (four years ago now, whoa):

• https://www.writethedocs.org/blog/newsletter-october-2019/#deciding-on-a-new-tool

• http://lauriston.com/requirements_sanitized.pdf

Where to find out more about Anne Gentle:

• LinkedIn

• docslikecode.com (Get a copy of her book or read her articles.)

• Check out her recent interview on RedMonk