Improving documentation with web analytics, Rachel Potts at TCUK

Rachel Potts (@citipotts) held a 3-hour pre-conference workshop at TCUK, showing and instructing us how to use web analytics (such as Google analytics) to monitor and improve documentation. We went through three use cases, you can

  1. Answer specific questions, for example, how often was a certain page viewed. This is the simple, obvious use case where you just look at one or few numbers without having to do any data tringulation.
  2. Measure strategic process. This means to analyze available data top-down to find out whether documentation serves an intended purpose. For example, if exception handling pages in the online help have feasible numbers for page views and time on page, while customer support calls for the corresponding issues decrease, your strategy to offer self-service error recovery in online help probably succeeds.
  3. Measure content use. This means to analyze bottom up to find out what new insights can be teased out of the available. Take an online shop, for example. If you relate search terms with the products that were ultimately bought in the same visit, you can start to build a glossary of products which your customers relate to one another. This is not the well-known “Customers who bought that have also bought this…”. Instead, you might find that people looking for “loafers” often buy “sneakers”. Or people looking for “equity” in the online help often wind up at the “stocks” page sooner or later.

For the specific improvement of documentation, Rachel had prepared several exercises. The one I found most helpful had us develop an action to achieve a business goal with documentation content. This action consisted not only of a formula, a target and a frequency of what to measure in web analytics, but also of the underlying purpose and the underlying assumptions.

Rachel was very explicit on that last point: She warned us that we should always keep in mind our assumptions in our interpretations and in what we define as a successful outcome!

– I had never thought through how web analytics could be applied to documentation, so this was an insightful workshop for me. I believe that all three use cases can be applied successfully to complement user analysis and surveys. However, having documented web analytics software in a previous  job, I am skeptical about any absolute numbers to come out of the analysis. Instead, I trust them more to indicate relative change or progress.

Your turn

How have you used (or would you use) web analytics to monitor and improve documentation? Feel free to leave a comment.

Getting ahead as a lone author, my TCUK presentation

I’ve just held my first presentation at a technical writing conference: On September 22, I spoke about “Getting ahead as a lone author” at the ISTC’s conference “Technical Communication UK” near Oxford.

If you’ve been following this blog, you will recognize the theme: I’ve covered several angles of this topic throughout the year. My presentation was basically a condensed version of many of the ideas on this blog, neatly wrapped into 5 best practices, and with the opportunity to ask questions or to comment.

I was glad to have the first slot after the opening keynote, so I could get my presentation out of the way: As much as I was looking forward to it, it did interfere with my attention and general enjoyment, as I kept thinking about whether it was too long or not appropriate in some way.

The opening keynote then set a very comfortable tone: The topic was serious, yet delivered with an ironic sense of humor. “Yeah,” I thought, “I can follow this…”

I counted 23 people in my audience – not a lot in a conference of 180, but it suited me just fine. While my pacing was brisk, I think, it was still easy to follow and engaging.

I finished after 30 minutes to leave 10 minutes for questions and answers. After all, I can’t claim to have any more experience or any better answers than any other lone author. Most of the questions asked for clarifications or further explanations and showed that many lone authors have similar concerns.

As I’ve found out from the comments, one of the weaknesses of the presentation was that I didn’t make all of my assumptions clear. For example, someone helpfully pointed out that authors in a (well-defined) agile programming environment don’t have many of the problems of authors in a waterfall project model as I described it.

On the whole, it was a very valuable experience: I now know I can hold a presentation and get a point across to a room full of fellow tech writers. And I hope to do it again someday.

I had some help on the way: I thank Linda Urban for first suggesting that I could do this. And Karen Mardahl for keeping me pointed in the right direction when I was getting nervous the evening before.

If you have something you are passionate about in your job, I can only encourage you to “get it out”. Write an article, start a blog or hold a presentation at a conference. Chances are it will mean something to your colleagues, either because they are concerned with the same topic or infected by your enthusiasm. And don’t be afraid to seek out help, none of us has been born an author or a presenter, and you’ll find many people willing to help you along.


  • My presentation slides: You can see and download my slides which have been enriched to link to blog posts and web sites with more resources.
  • How to hold a presentation: There are a lot of web pages about this, these two have helped me to prepare and to make me confident that I didn’t forget anything.

If you have any feedback on the presentation, whether you attended it or not, I’d be happy to hear it!

Getting ready for TCUK

Take half the slides and twice the nerves.

That’s the lesson I learned as I spent last week getting ready for the TCUK conference and my presentation “Getting ahead as a lone author”. (The lesson is a variation on the old travel advice “Take half the clothes and twice the money” which was useful before credit cards and ATMs…).

Finishing the presentation

… took much longer than I thought. Basically, it’s just as writing good documentation: Knowing what you want to say is a prerequisite. But saying it in the most effective way is what takes time.

But it was worth the trouble. When I was done, I had a nice presentation: A catchy introduction nicely segued into an elegant sequence of nine best practices, followed by a concise summary and conclusion. 30 minutes, plus 10 minutes for Q&A, didn’t seem so terrifying anymore.

If you’ve presented before you probably worry now. It took me some practice to find out what you already know:

30 minutes is much shorter

… than I thought. There’s no way to fit all this into 30 minutes. So I spent more time yet on taking stuff out again. I conflated 2 of the 9 points and dropped another 3, so I’m now down to 5 best practices. That clocks in at around 30 minutes.

Again, it was worth the trouble since I’m now sure I have the best, most focused content ready to present. Highlights include a painting by Carl Rakeman and the “Kick Ass Curve”.. 🙂

If you attend TCUK, consider attending my session on Wednesday at 10:00, right after the keynote address. If you don’t, stay tuned, there will be post-conference notes in this space!

Capture everything, or: Are you “Getting Things Done”?

Of course you are getting things done – like most of us tech writers… But do you apply the David Allen’s GTD method from his book Getting Things Done: The Art of Stress-Free Productivity (GTD)? (Hence the quotes into the title…)

Over the years, I’ve found a few principles from Allen’s method especially valuable for tech writers, whether you are a manager or not. They can also be found in other productivity contexts. I’m describing them as parts of GTD, because it’s a well-known method that explains its principles well – even if the implementation can be cumbersome. But that’s what Zen to Done is for… 🙂

Today, I discuss my #1 GTD Principle for Tech Writers:

Universal capture

The idea of universal capture (aka ubiquitous capture), as I understand it, is this: You’re most productive when you concentrate on the task at hand. You don’t waste “brain cycles” remembering other task. To free your mind from all this remembering, you dump everything into a consistent, trusted system – your universal capture. I find this blatantly obvious – and difficult to do well and reliably.

The problem

As I update documentation, new features need to be described in release notes, one or several manuals and the online help. At the same time, the occasional gap or error needs to be fixed in manuals and/or online help. Due to time and system constraints, I cannot address each issue in all formats as soon as it pops up.

So I need a way to capture any and all issues reliably, so I can forget about them until it’s time to address them. At first, I tried to use my inbox by sorting issues into one sub-folder per format. This approach had several problems:

  • Some issues needed to be addressed in more than one format or more than one manual.
  • Some issues were thrown up in phone calls or when colleagues stopped by with a manual in their hand.

My solution

I’m now using a personal wiki in our intranet which is, for transparency reasons, open for everyone to see and edit. This page is quick and easy to access and edit. It makes few demands on structure and allows me to be as brief or as elabrate as I can be at the “capturing moment.”

Each deliverable has a section of its own, so I can have the same entry in several sections if necessary. When it’s time to update a deliverable, I know I’ll have all issues captured in my wiki list. As I work on it, I strike through each addressed issue. Around the publication date, I condense all issues into a summary of major updates.

More tips and tricks

Leo Babauta (creator of Zen to Done) shares a few general insights about how ubiquitous capture works and when it doesn’t.

Your turn

Do you use universal capture? Or another method of GTD? Do you find it useful? What tools do you use? Please feel free to comment!

Welcome to summer reruns, part 2

My blog and I are taking it a little easier towards the end of the summer.

I’ve had a wonderful time with this blog so far, and I thank each and every one of you for reading, lurking or commenting. I’ve learned a lot from your comments, and I appreciate your support! It’s been a warm summer’s breeze… 🙂

As we’re gearing up for the new season, here are some reruns from the last year or so.

Popular posts from my blog

Top 10 things that users want to do in a help system

This is one of my two most popular posts by far where I draw a parallel to a department store or a library to illustrate how customers want to navigate each one.

Reality check: Writing for scannability and localization

What happens if our nobel attempts at clear topic structures and parallel sentence structures meet head on with unsuspecting readers?

Portable apps for tech writers

This is the first post in a four-part series where I recommend free and (mostly) light-weight applications that can help any tech writer in his daily tasks.

Noteworthy posts from elsewhere

If you want to get an introduction into content strategy, I think, you could do a lot worse than reading these excellent posts:

Complete Beginner’s Guide to Content Strategy

Content Lifecycle

The extraordinary world of content strategists

The last two posts are beginnings of series, so be sure to follow the links at the end of each.