Category: Write the Docs

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

Measuring Value for WriteTheDocs Boulder

Presentation for WriteTheDocs-Boulder
Link to presentation given to WriteTheDocs-Boulder

I had the pleasure of joining the Boulder/Denver WriteTheDocumentarians at their meetup in Denver, last month. I presented a short talk on what I had learned about measuring the value of content that is typically produced by technical writing, which started an enlightening conversation with the group.

I’ve linked the slides and provided a brief narrative to go with them, here. Unfortunately, you had to be there to enjoy the conversation that followed–a good reason to not miss these events!

Measuring content value is a process, not a destination

For some, the idea of measuring the value of technical writing requires a shift in thinking. Measuring the value that content provides is just one step in the process of setting and evaluating content goals (see also Design Thinking). Without getting too philosophical, the first realization to make is that

You can’t measure value until you define what is valuable.

Value, however, can take many shapes, and different people in your organization will likely define value differently, especially when it comes to content.
Continue reading “Measuring Value for WriteTheDocs Boulder”