Coal miners used to bring canaries with them into the mines to detect toxic gasses commonly found in mines. Canaries would die when the gasses were present, but while still at levels not fatal to humans. They were an early-warning sign. The challenge is that you would have to keep an eye (or an ear) on them to heed their warning. If you were busily mining your coal (a rather noisy job to begin with), you could easily overlook the warning sign of a dead canary—much to your peril.
Think of your technical writer as a canary (that can also type).
I read a lot about how API documentation is deficient, how it should be automated, and how it should be made easier to produce and update. I’m all for making it easier to write and maintain, but I think replacing the canary with a device or process that won’t let you know when there’s trouble ahead is solving the wrong problem.
Why IS your API hard to document?
It could be that it’s toxic and you haven’t noticed the dead canary.
I read The Top 20 Reasons Startups Fail that studied the reasons that failed startups reported as why they failed and the reasons looked surprisingly similar to challenges I’ve seen in my career of documenting and researching APIs.
Coincidence? Let’s take a look.
There’s no market need
This is the #1 cause for failure cited by the startups reviewed in the CB Insights study. What does this have to do with an API?
If there’s no market need, what user cases will the documentation address? To whom will the technical writer be explaining all these features? With what burning customer pain-points or unmet needs will the documentation connect? What sort of demos and tutorials will need to be written (or referred to) that demonstrate solutions to customer problems? Why will anyone care?
If those questions are hard to answer, that’s an immediate problem for the technical writer, but it’s also a bad sign for the API and the business’ stakeholders.
That there’s no existing market, doesn’t mean there’s no market need, but, generally, if there’s no market need, there won’t be much of a market.
The 13 Top Reasons Why Startups Fail quotes the CB Insights report that found 42% of startups said they failed because there was no market need for their product or service and suggests these reasons for how this could be the case. Ask yourself (honestly), do any of these apply to your API:
- You solved a problem that you had, but that no one else has.
- There are already other (and/or better) solutions available for that problem.
- The market isn’t ready (yet).
While the lack of a market need identifies issues bigger than the documentation, it certainly doesn’t make documenting your API any easier. Likewise, if it is difficult to articulate market needs and pain points to the technical writers, is that because they don’t exist?
What can you do?
Do some honest market and user research before you start cranking out code. (I know, where’s the fun in that, right?) Your technical writers could help you here, too, if you asked them. After all, the technical writers’ goal is to contribute to the product’s success. Documentation is only one of the tools they bring to the table to do that. Some other things they could help you with include:
- Going out into the field and talk to your potential customers. Get to know what they do, how they do it, and where they do it. You might have a solution that could solve their problems with just some minor adjustments. But, the lack of those adjustments can be costly.
- Working with you to make your API easy to use. Knowing your customers can help you sync your API’s functions, terminology, and application to the problem such that the fit is obvious. This makes it easier for your future customers to see how it will benefit them and it also makes it easier for the technical writers to write the documentation.
- Helping you know whether this just isn’t the right solution or the right time. Research can help you know if that’s the case and, if not, when it might be. If it’s not now, you’ll be ready to jump on it when it is—and, in the meantime, you can do something else for which there IS a real and immediate need.
If you didn’t do this before you started, you can still start now. The sooner you have the information you need, the sooner you can use it to make informed decisions about what to do next.
Ran out of cash
This is a reason many technical writers are familiar with, although they might not recognize it as such. In the 15 years or so I’ve worked as a technical writer, the writing staff is almost always very “lean” (a.k.a. severely under-resourced). While that makes the technical writer’s job difficult, it’s also a sign that your API might be in trouble. If you can’t afford what you need to get the job done (and you didn’t answer the critical questions in advance to know what you would need), it will be easy to press on in the absence of any market need until you run out of cash.
Business model failure
Six years ago, 5 Reasons Why Startups Fail listed this as the #2 reason for startup failure. CB Insights lists it as #7, but, either way, it certainly contributes to running out of cash.
OK, but what does this have to do with API documentation?
If the market need describes what your API does for the customer, the business model describes what your API does for your organization. If your API isn’t going to feed the organization somehow, it’s going to make the technical writers’ job more difficult, too. In addition to making it hard for the technical writers to get subject-matter experts to contribute to the documentation, it’s going to contribute to under-resourcing the documentation team.
It’s also going to make it hard for technical writers to present the documentation in a way that supports both the customer’s interests and that of the business. Yes, they can both be met, but they need to be clear.
What can you do?
Ideally, your API’s success is tied to your customers’ success. Research and knowing your customer will inform your understanding of what success means to your customer, and hopefully, you also have a clear understanding of what success means (at a detailed level) to your organization. That makes your customers successful, your company successful—oh, and the technical writer’s job easier.
Not the right team
This is CB Insights’ #3 reason for startup failure and it definitely makes the technical writer’s job more difficult. What does this look like when manifest in an API? Typically, changes. Often, LOTS of changes. Changes to the conceptual models. Changes to the individual methods and objects. Even changes to the element names. While your technical writers might take this in stride (as they’ve seen it before), this is really your canary gasping for breath. Your customers will not have a lot of patience for this type of disruption.
But, “Agile!”
Maybe, but remember that you can’t appear to be more agile than your customer. This is especially true for APIs.
What can you do?
Research can help inform the decisions and diplomacy can help minimize ruffled feathers (two skills that technical writers often find the need to develop early in their careers), but at the end of the day, it’s the organization’s management that will make this work (or contribute to the chaos).
Poor product
This is #5 in 5 Reasons Why Startups Fail and #6 on CB Insights’ list. They describe a “poor product” in a way that reflects being the wrong product for the job or being poorly executed. In any case, CB Insights found this reason for failure cited in 17% of the cases they reviewed.
What does this look like to a technical writer? A lot of additional work. I had a writing manager who called this work: “adding the verbal duct tape to make the product ready to ship.” A very accurate description of the work…and the resulting customer impression.
However, unless wrapping your product in duct tape before it ships is a key part of your company’s brand (and your product isn’t sheet metal tubes), this should be a warning.
What can you do?
The biggest source of this problem that I’ve seen in APIs is feature creep. If you don’t know what the market need is (or there isn’t one to begin with), it’s tempting to just add one more feature, “just in case” or worse, just in “edge case.” These additional features add more work (and the need for more documentation) such that when push comes to shove (as it always seems to do), quality is sacrificed in the name of quantity.
If you know what your customers need (as in, NEED), your API can focus on that and do it well, rather than providing a lot of features they might need (some day, maybe) and doing them poorly. This has the double bonus of making it easier for customers to see and apply your API’s value proposition, and making the technical writers’ job easier.
Bottom line
If your API is hard to document, it could be a sign of more fundamental problems. Do yourself, your customers, and your technical writers a big favor and make your APIs easy to document. I have a post that provides an overview (Start with API Usability), but there is lots of information on how to do this available online.