Category: Technical writing

Posted on

Unqualified best practices are just slogans

I had the pleasure of joining Tom Johnson in another podcast and one of the topics we touched on was that of so-called best practices. Today, I stumbled across this post in a thread about high-tech job interviews:

On a personal note, it was actually a series of such experiences that convinced me to take my current job in academia.

One of the replies linked to this post: Best practices considered harmfull [sic] which summed it up as “Work out what your best practice is, work out how you can improve yourself.”

Unfortunately, by the time I got to this point in my feed, my blog reflex had been triggered, and here we are.

If we have to find our own best practices, what’s the point of having best practices?

Good question.

Continue reading “Unqualified best practices are just slogans”

Posted on

Yes, YOU can write docs as cool as Twilio’s

After attending Write the Docs 2018 (Portland, edition) and watching a YouTube video, I’ve got it figured out: How you (i.e. anyone) can create documentation as cool as Twilio’s–a consistent entry in lists of the best API documentation examples.

All you need to do is follow these six steps:

  1. Think, plan, and work iteratively.
  2. Infuse user research and analytics into your entire writing process.
  3. Treat your documentation as a product.
  4. Do what’s best for your documentation customer.
  5. Create and support a writing process that enables contributions from outside of the writing team.
  6. Build the CMS that supports all of the above.

That’s it!

You’ll need to understand that it took them a few years to get to where they are, today. And, it sounds like they’ll keep moving the bar.

But, don’t be discouraged. The sooner you start, the sooner those three to five years will be behind you.

A little background

Twilio’s Kat King opened Write the Docs 2018 in Portland this May, starting the conference off with a strong sense of user testing and research. That always gets my attention at a tech-writing conference. The next session by Jen Lambourne continued by describing how she applied user research on documentation. I’ve been going to tech writing conferences for quite a while and I can’t recall going to one with such a user-research focus.

I’ll make references to these videos, in what follows in case you want to go straight to the source (something I always encourage). The practices they describe, however, are straight out of user-centered-design. You can also see some of my favorite books on the topic for more background.

What’s noteworthy here is that the Twilio team has applied them successfully to their documentation–proving, if nothing else, that documentation works like any other product (and perhaps works best when treated as one).

So, here’s how the steps work:

Continue reading “Yes, YOU can write docs as cool as Twilio’s”

Posted on

Tech comm education and the job market

One of the many informative experiences I had at this year’s WriteTheDocs 2018 conference was my chat with employers/recruiters at the Job Fair. My primary goal was to learn what they looked for in their technical communication interns and entry level recruits, so I could bring that back to school. What I learned was not surprising, having only recently left industry for academia, but it was a wake-up call.

Recruiters want people (even their interns) who have experience and they want current and relevant experience.

I agree, that’s a bit of a Dog bites man story. Of course they do. All other things being equal, having current and relevant experience is almost always better than not. I suspect it is because the assumption is that with it, the person will become a productive team member sooner than later. What I think is often overlooked is how other idiosyncratic aspects of the specific job might have a greater influence in the time to productivity, such as the onboarding support (discussed in Sarah Day’s talk at this year’s conference), but that’s not something that I, as an educator, have much control over (unless you’re hiring me to consult on the process, of course).

What an intern needs

One of the things I have to keep in mind when reviewing my notes is that I was at a software documentation conference and the companies I talked to were software companies with open-source software products to document. In that context, it was natural that they were looking for writers with experience in their product domains: open-source tool experience (Git, GitHub, Markdown, etc.) They also looked for a passion for documentation—as evidenced by experience in such tools (e.g. documenting an open-source project in GitHub). I don’t know how many of these observations transfer to looking for writers in other industries.

Continue reading “Tech comm education and the job market”

Posted on

Write the Docs 2018

Had an amazing experience at the 2018 WriteTheDocs conference in Portland, OR, last week. This was the first time I’ve been able to attend the conference, although I’ve followed it for years. While you can watch the formal talks from this, and previous, conferences on YouTube, it really is nothing like attending in person. What you don’t get to experience from the excellent YouTube videos, that is literally tangible in person during the conference, is the supportive sense of camaraderie, support, and acceptance from the participants.

The talks were a collection of first-person testimonials and experience reports by experienced and practicing (well, except for me, perhaps) technical writers and managers. The talks all had a practical focus and tangible, practical takeaways that the audience could take with them and put to work on the job.

Bottom line, if you are a technical writer and can go to only one conference a year, I recommend this one quite highly.

The downside to the conference is ther are too many places to be at once. In addition to the formal talks in the ballroom, a parallel “unconference” and job fair took place simultaneously in a smaller room below the ballroom. To complicate matters further, there were all the people I knew from the WriteTheDocs Slack to meet in person.

Continue reading “Write the Docs 2018”

Posted on

Collecting feedback about your documentation

KC-135R Engine Instruments showing various indications during testing
Lots o’ data

In my thread on user interactions with documentation, I suggested that you want your measurement instrument, usually some form of survey question(s), to influence the experience you’re trying to measure as little as possible. From a measurement standpoint, that’s nothing new. You never want your measurements to influence that which you’re measuring to prevent contaminating your measurement.

In the case of measuring feedback, or in this case, documentation or experience feedback, a recent tweet by Nate Silver (@NateSilver538) described how the use and perceived use of the measurement system had contaminated the data collected by Uber/Lyft (and countless other services).  He tweeted, “Given that an equilibrium has emerged where any rating lower than 5 stars means your Uber/Lyft driver was bad, they should probably just replace the 5-star scale with a simple thumbs-up/thumbs-down.”

Continue reading “Collecting feedback about your documentation”

Posted on

From getting started to getting finished

As a technical writer who occasionally does some development on the side, I appreciate a fast Time to First Hello World (TTFHW)—the time it would take to create and run a simple program using a new (to me) API. The time to get started, in other words. The Nest API documentation I recently reviewed  reminded me of a much less frequently mentioned notion, the time to get finished.

If you’re not familiar with TTFHW, it is basically, how long it takes a new user to:

  1. Find your product
  2. Resonate with its value proposition
  3. Test it out to verify it provides them with a viable solution

The metric for this is operationalized by how long it takes someone to write a simple program to demonstrate step 3. From a measurement standpoint, this is a reasonable goal in that:

  1. It’s tangible and relatively unambiguous in its meaning (the reader was successful in accomplishing the goal).
  2. It can be measured accurately if your help documentation provides a way to link the documentation to the use of the API, through a user-specific key or interactive development environment.
  3. It can show a tangible engagement metric to show that your product is attracting and engaging potential customers.

While it’s good to use that as a metric for engagement and potential adoption, it’s important to not treat it as the only metric that counts because it doesn’t necessarily represent retention or other aspects where the money is made or lost.

Continue reading “From getting started to getting finished”

Posted on

All is not gold that glitters, especially with API docs

I saw some buzz about the Nest developers’ API explorer and its corresponding developer documentation so I took a look. For many reasons, new API documentation formats attract a lot of buzz (and envy) among technical writing circles. From the technical writers wondering, “How can I make my documentation to look like this?” to the executives demanding, “Why don’t our docs look like this?!” Rarely, do I hear, “should our docs look like that?” But, that’s what I’m here for (it seems).

Should your API docs look like the Nest developers docs?

The answer is, of course, maybe.

I don’t have any inside information about why or how the writers of the Nest documentation did what they did, so the following analysis is based on my observation and inference.

What it does well

It has a very clean UI. Clean presentations inspire confidence and professionalism.  The styling is consistent and aligned with the consumer site’s branding, which implies they consider their API docs to be a part of their brand promise. I think that’s a good sign. Externally, it shows that the company considers the API to be part of the product’s brand and not a bolt-on or afterthought. As a developer, this is reassuring.

As first impressions go, it has a very nice curb appeal.

Continue reading “All is not gold that glitters, especially with API docs”

Posted on

If your API is hard to document, be warned

Coal miner looking at canary in cageCoal 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?

Continue reading “If your API is hard to document, be warned”

Posted on

The right tool to measure your content’s performance

The past few days, I read a couple of articles on content metrics from the blogosphere: one had promise but ultimately indulged in some analytic slight-of-hand, while another actually made me smile and its focus on an solid methodology gave me hope.

Why is a solid methodology important? It’s the basis of your reputation and credibility. It’s the difference between knowing and guessing. These two articles reflect two examples of this.

First, the one that had a sound approach, but some flawed measurement methods.

How metrics help us measure Help Center effectiveness

This article has promise, but trips and falls before the finish line.  To its credit, it recommends:

  1. Setting goals and asking questions
  2. Collecting data
  3. Reviewing the data
  4. Reviewing goals and  going back to #2
  5. Lather, rinse, repeat  (as the shampoo suggests)

As a general outline, this is as good as they come, but the devil is in the details. If you’re in a hurry, just skip to the end or you can…

Continue reading “The right tool to measure your content’s performance”

Posted on

More API documentation resources

I added a couple of new resources to help the technical communication community. Here is the current list of lists.

  1. Some of my favorite user experience books can be found at Selected readings on user experience design.
  2. My list of API documentation articles -non academic has grown from 18 to 30 articles. Most new ones are from the past year, but I found a few earlier articles that I seemed to have missed in my last update.
  3. My original list of academic (for the most part) papers contains the articles that I’ve cited in various papers.
  4. A recent post contains some recent academic work about API documentation that I haven’t yet filed away in any of the preceding lists.

Plotting them over time shows some recent growth in frequency as with the academic articles on API documentation, however there are 66% more academic articles on the topic in my [ever expanding] collection, so it might still be too soon to draw and comparisons.