A brief history of API Docs

I published my first API around 1988 for a peripheral to the IBM PC in which the API consisted of software interrupts to MS-DOS. (A software interrupt is similar in function to a procedure call, but used for operating system and device driver functions. I didn’t write the documentation (at least not the published version), but a couple of co-workers and I wrote the interface.

Later, I want to say in 1997-ish, I wrote the API provided by the Performance Data Helper (PDH) dynamic link library (DLL) that shipped in Microsoft Windows NT 4.0 (IIRC). I didn’t write the documentation for this API either as I was still developing software at the time. A super technical writer did the heavy lifting of making sense out of the functions the PDH.DLL provided.

While this isn’t a particularly impressive resume of API development, it shows that APIs and I go way back. They are a very useful tool for solving many problems. Yet, over the past 30+ years that I’ve been using, developing, and documenting APIs, there hasn’t really been much written about their documentation–until recently.

In my informal count (i.e. what I could find on Google while having my morning coffee a few days ago). I came across 17 articles and blog posts on the topic in just the past seven years (full list at the end of the post).

For the curious, here is some of the research that supports what I’ve read in some of these articles. Continue reading “A brief history of API Docs”

Tech comm myths site is live

I just launched TC Myths, my site in which I’ve collected all the myths about technical communication that I could find.


It started out as a quick lit. review, but the list grew more quickly than I expected (or imagined). I originally thought the list of myths would result in a duplicate of a similar list at UX Myths and then that would be the end of it. As it turns out, there is very little overlap. It also turns out that TC Myths are (or have been so far) much harder to research, compared to the UX Myths. The myths are also mysterious, which is why I’ve opened it up to comments and contributions.

I’m trying to understand why Technical Communication has (by my last count) over 70 different myths! Do we really need that many?

So, what does it take to be a TC Myth?
Continue reading “Tech comm myths site is live”

Google Developer Documentation Style Guide has been released

The good news is that Google has released the Google Developer Documentation Style Guide . The bad news could soon be that Google released the Google Developer Documentation Style Guide .

It doesn’t have to be that way.

I’m delighted to see that the style guide includes, albeit below the fold, the advice to:

Remember that everything in this guide is a guideline, not a draconian rule.

Personally, I think this caveat should be on every page as part of the chrome, but at least it’s in the introduction. Unfortunately, my cursory review of the guide shows that the rules provide little context to help readers (in and out of Google) decide when would be good time to break a given rule and what the consequence or effect of that might be. But, this is not new. It has been a deficiency in technical communication guidelines and best practices that I’ve complained about for several years now. Maybe in v2?

Getting started

The highlights are a good place to start and provide a short cheat sheet of rules that are relatively universal and, while they don’t provide any resources or background for why these are good practices, I’m familiar with research that supports most of the suggestions, but I’m an outlier.

Hey, Google editors, for v2, please provide links to the background and research behind these guidelines to help readers–that is, the technical writers who will be applying these principles–understand why these are good practices and when they might want to make exceptions as you suggest in the opening caveat.
Continue reading “Google Developer Documentation Style Guide has been released”

Measuring your technical content – What about…?

If you’ve been following the preceding posts on measuring content, as the use-cases and customer journey paths start to become less funnel-shaped, this is about the point where whataboutism starts to occur.

In the post on measuring Tutorials, for example, I assert that “the customer’s goal in reading a tutorial is to accomplish something outside of the web,” making detecting and measuring their success difficult to do from within the topic. While the definition of a tutorial might make that seem like a pretty clear goal, that doesn’t make it immune to whataboutism.

Whataboutism can enter the discussion at this point in the form of “What about the people who come to the tutorial topic looking for a code sample to copy and paste? They don’t want to learn anything.” Or, “What about the executive who looks at the tutorial to see if it addresses a particular issue they care about?” Or, what about…  You get the idea. From what I’ve seen, it’s easiest for whataboutism to enter the discussion when the goals are broad and vague and the data supporting the goals and their subsequent measurement are scarce.

(Does that sound like a content project to you?)

So, what can you do about the “what about…” cases?

Continue reading “Measuring your technical content – What about…?”

Measuring your technical content – Part 3

In my recent posts, Measuring your technical content – Part 1 and Measuring your technical content – Part 2, I described some content goals and how those might be defined and measured for Introduction and Getting Started topics. In Part 1, the interaction was funnel shaped, while in Part 2, the funnel metaphor applied only in one of the two customer journeys through the page.

In this topic, I talk about Tutorials and How-To topics and how the funnel metaphor becomes less appropriate as customers goals move beyond the web experience.

It’s time to get creative (scientifically, of course).
Continue reading “Measuring your technical content – Part 3”

Measuring your technical content – Part 2

In my previous post, Measuring your technical content – Part 1, I described some content goals and how those might be defined and measured for an introduction topic. I this post, I look at Getting Started topics.

Getting Started topics

If Introduction topics bring people in by telling them how your product can help them, Getting Started topics are where you show them how that works. Readers who come here from the Introduction topic will want to see some credible evidence that backs up the claims made in the Introduction topic and these topics are where you can demonstrate that.

Technical readers will also use this as the entry point into the technology, so there are at least two customer journey paths intersecting here.

  • One path will come to a conclusion here, moving from the Introduction page to see the value and then the Getting Started topic to see how it works
  • Another path starts from the Getting Started page (already understanding the value proposition of the product) and moving deeper into the technology to apply it to their specific case.

Because at least one of the customer journeys through the Getting Started topics are less funnel-shaped than for the Introduction topics (some are almost inverted funnels), it’s important to start with the goals and required instrumentation before writing so that you can design your page to provide the information that the customer needs for their goals as well as the data you’ll need to evaluate the page (your goal).

So, in that case, what how might you measure such a topic’s success?

Continue reading “Measuring your technical content – Part 2”

Measuring your technical content – Part 1

This started out as a single post, but grew, and grew, and… Well, here’s the first installment.

After the last few posts, it would be easy to get the impression that I don’t like Google Analytics.

Not true.

I just don’t like when it’s treated like it’s the only tool that can collect data about a web site—especially a non-funnel (informational) web site.

In this collection of posts, I’ll look at my favorite topic, API documentation, and how you might analyze it in the context of the customers’ (readers’) journeys. This analysis doesn’t have to apply only to API documentation, because it’s based on customers’ goals, which are more universal and, if you look carefully, you might see a customer goal that matches some of your content.

So let’s start with the basic questions…

Continue reading “Measuring your technical content – Part 1”

Google Analytics just makes me sad

In my last post, I talk about how Google Analytics isn’t very helpful in providing meaningful data about technical or help content. It can’t answer questions like: Did it help the reader? Did they find it interesting? Could they accomplish their task/goal thanks to my content? What do readers really want? You know, simple questions like those.

While a little disappointing, that’s not what makes me sad.

What’s sad is that the charts on the dashboard have all the makings of dysfunctional communication. For example, the dashboard seems to tell me, “You’re not retaining readers over time.” But, it can’t, or it won’t, tell you why.

Awww, come on, gimme a hint?!

Continue reading “Google Analytics just makes me sad”

The answer is Google Analytics—what was the question?

Lately, I’ve seen a collection of blog posts about using Google Analytics for technical or, more generally, informational content that seem to use a formative research method, that goes something like, here’s the data you can collect, now let’s imagine the questions that it might answer. It’s not that this method is not valid, just that it’s one that is usually done at the beginning of a project and it doesn’t scale particularly well. What many technical communicators could use on a daily basis is summative data on how their content is doing on a day-to-day basis.

Can Google Analytics provide useful summative metrics? Sure, but very few that monitor what matters to the reader. Most of them fall into the vanity metrics category for informational content. The reason is that people don’t come to informational sites to read web pages or click links (which is what Google Analytics tracks). They come to accomplish a goal—a goal that is likely not found in your informational web site. Your site, if it is doing its job, is a means to another goal.

So, how can you measure whether a reader accomplished their goal? And, by measure, I mean observe directly and not infer (or imagine) reader behavior.

Continue reading “The answer is Google Analytics—what was the question?”

Still buzzing about StackOverflow documentation

I don’t think I’ve ever seen a technical documentation project get so much attention (be it successful or not). The good news is at least people are talking.

But the talk is still looking at only symptoms. The conversations have been interesting but fall short of the root causes.

The documentation project kick-off post identified these problems with documentation (paraphrased here) that Documentation intended to fix:

  • Documentation is often an afterthought
  • Documentation is lacking in examples
  • Documentation is rarely complete

The kick-off described the problem, fundamentally, as a shortage of documentation and approached the solution by making it easier to add more documentation (articles and examples). Consider each of these points as discussed by some other technical writers. Continue reading “Still buzzing about StackOverflow documentation”