To help users discover new features and major changes, the Chrome DevTools team embedded release notes into the DevTools UI. The success of this approach has fundamentally changed how I approach documentation discovery in general. I now look for ways to contextually link to the documentation from the product.
Technical writers talk a lot about being empathetic with readers. I agree that it's a crucial skill but frankly I think that the discussion is starting to degenerate into lip service. We need more concrete guidance on how to cultivate empathy in our documentation. In this post I propose that it's our duty as technical writers to start recording our real-world first experiences with documentation and share these recordings with other technical writers so that we can see what it's truly like to use documentation when in need.
The experience of using a documentation site may be as important as the quality of the content on that site. This post shows you how to use Chrome DevTools to quantitatively measure whether your documentation site is an asset or a liability.
First impressions of Twitter's "was this page helpful?" UX.
Parametric Press enables its readers to control how much information they see via a slider that has 4 options: "TL;DR", "Essentials", "Highlights", and "Everything". This post explores whether this feature would be useful in documentation. My initial impression is that the ROI does not justify the effort.
Recently I discovered that a supposed documentation "best practice" may not actually stand up to scrutiny when measured in the wild. I'm now on a mission to get a "was this page helpful?" feedback widget on every documentation page on the web. It's not the end-all be-all solution, but it's a start towards a more rigorous understanding of what actually makes our docs more helpful.
Asking users whether or not they found a doc helpful is an easy way to measure the quality of a doc. However, very few users take the time to leave feedback. If you've only got 2 or 3 responses on a doc, you can't trust that the data represents the opinion of your audience at large. I've been conducting various experiments to find out how to maximize the response rate. In this experiment, I learned that red buttons appear to generate significantly more responses than blue ones.
I conducted a scientific experiment to find out if specific, more personal requests for feedback generate more responses than generic ones. The results reject the hypothesis. More personal requests for feedback do not generate more responses than generic ones.
A proposal for an automated way to identify big changes in docs.
This is my lightning talk from the Write The Docs 2018 conference in Portland. I talk about using the scientific method to try to improve the response rates in "was this page helpful?" feedback widgets.
The purpose of metrics is to discover insights about how we can help users accomplish tasks as quickly and effectively as possible.
Idolatry is alive and well in modern society. We created our economies and our governments, but now we worship them as forces greater than humanity. If we want to change society, we can begin by challenging any thoughts that treat it as a force greater than us.